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Preface 



This manual describes the VAX APL interpreter, including VAX APL 
language and programming elements, facilities for controlling the VAX APL 
environment, the interaction between VAX APL and the VMS operating 
system, and VAX APL's I/O capabilities. 

Intended Audience 

This manual is intended for experienced APL programmers. This manual is 
not a tutorial and is inappropriate for novice users. Programmers experienced 
with other languages such as FORTRAN or BASIC can learn VAX APL from 
this manual, but are advised to study it in conjunction with an APL language 
primer. 

Related Documents 

The VAX APL User's Guide describes the VAX APL interpreter and the 
environment in which it operates. The VAX APL Installation Guide contains 
instructions for installing VAX APL on the VMS operating system. The 
VAX APL Installation Guide also explains how to install QAPL, the license- 
free, execute only version of VAX APL. 

To find out more about the VMS system, refer to the VMS system documents 
listed in the Introduction to VMS or use the Help utility by entering HELP 
at the system prompt ( $ ). The VMS DCL Dictionary and the Introduction to 
VMS System Management provide detailed information you may need to know 
to use some of the features of VAX APL. 

Product References 

In this document, VAX APL is referred to as APL. 
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Conventions 

The following conventions are used in this manual. 



Table 1 Documentation Conventions Table 



Conventions 



Meaning 



Default values used in 
examples 



Delimiting pairs 



UPPERCASE 



A B K 



italics 



Quotation mark ( ' ) 



[] 



The default value for the index origin (a 10) is l , unless 
explicitly stated to be . Numeric print precision (Q PP) 
is 10 digits. Enclosed arrays are displayed with boxes 
around enclosed items and with all values in the top left 
corner of the display areas. This is done using: 

DDC i- fl*12 3) ' + + + + | |--' 

This manual uses a text ft ; other delimiting pairs may be 
any of the following pairs: 



DD 



QD 



Uppercase words and letters, used in format examples, 
indicate that you should type the word or letter exactly 
as shown. 

The APL characters A , B , and K are used in generic 
descriptions of command formats. A represents a 
left argument, B represents a right argument, and K 
represents an axis argument. 

Italicized lowercase words and letters, used in format 
examples, indicate that you are to substitute a word or 
value of your choice. 

The term quotation mark refers to the APL single 
quotation mark ( ' ). 

The equivalence symbol means "is equivalent to". 

The double square brackets indicate that the item or 
string of items inside the brackets is optional. Individual 
items within a string of items are delimited by the .ab 
character, which indicates that you may choose only one 
item from the string. 

Single square brackets that appear in the format 
specification for a language element are required syntax 
for the element being described. 

(continued on next page) 
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Table 1 (Cont.) Documentation Conventions Table 



Conventions 



Meaning 



n/a and n/s 



Braces are used to enclose lists from which one 
item must be chosen. The items in such a list are 
delimited by the | character. For some user-defined 
operation headers, the braces are required syntax (this 
requirement is described in Chapter 3 of the VAXAPL 
User's Guide). 

These abbreviations indicate that something is Not 
Applicable or Not Supported in the context being 
discussed. 

A horizontal ellipsis indicates that the preceding items 
can be repeated one or more times. A comma preceding 
the ellipsis indicates that successive items must be 
separated by commas. 

A vertical ellipsis indicates that not all of the statements 
in an example or figure are shown. 



Color 
<CRxLF> 

Ctrl/X 



Color in examples shows user input. 

The <CRxLF> symbol indicates the presence of a 
control sequence representing a Carriage Return and a 
Line Feed. 

The Ctrl/X symbol indicates that you must press the key 
labeled Ctrl while you simultaneously press another key, 
for example, Ctrl/C, Ctrl/Y, Ctrl/O. 

A symbol such as |xxx| indicates that you press a key on 
the terminal. For example, the | Return | symbol represents 
a single stroke of the Return key on a terminal. 



Unless otherwise noted: 

• All numeric values are represented in decimal notation. 

• You terminate commands by pressing the Return key. 

• All examples in the manual are executable, and comments beginning with 
the lamp (r ) symbol are part of the examples; comments surrounded by 
parentheses are not part of the examples. 
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1 

VAX APL Primitive Functions and 

Operators 



VAX APL provides functions that allow you to perform various operations with 
arrays. These functions are termed primitive because they represent the basic 
capabilities of the language. You do not have to write programs to perform 
these operations; they are built in. That is, the APL interpreter already knows 
how to perform them. 

Primitive functions may be classified by the characteristics of their arguments 
and results. One distinction is whether a function is scalar or mixed. The APL 
primitive scalar functions perform scalar (or scalar-like) operations; the APL 
primitive mixed functions perform mixed-rank operations. 

Primitive functions are either monadic or dyadic. Monadic functions require 
only one argument, which is placed immediately to the right of the function. 
Dyadic functions require two arguments, one on either side of the function. 

Primitive functions also have a domain and a range. The domain of a function 
is the permissible type, shape, and values of its argument arrays; the range is 
the permissible type, shape, and values of its result array. 

In addition to describing the APL primitive functions, this chapter describes 
the APL primitive operators (operations that produce functions as results), and 
the specification function (a function used to associate values with identifiers). 

APL also provides functions for system communication and for I/O. These are 
explained in Chapter 2, Chapter 3, and in Chapter 5 of the VAX APL User's 
Guide. 
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APL Primitive Functions 

1 .1 Primitive Scalar Functions 

1 .1 Primitive Scalar Functions 

The primitive scalar functions include the arithmetic, relational, and logical 
functions that almost everyone is familiar with — addition, subtraction, equality, 
and, or, and so on — plus a few operations that are less familiar, such as residue 
and roll. These functions are called scalar functions because they take scalar 
arguments and return scalar results. For example: 



6 



4 



!3 ^FACTORIAL OF 3 

2 + 2 



The primitive scalar functions are extended on an item-by-item basis when 
the argument array is not a scalar (the argument can be any shape, simple 
or enclosed). In effect, APL operates on a sequence of scalar arguments and 
returns one value for each argument. This process is known as scalar product. 
For example: 

13 4 5 REACH ITEM IS TREATED AS A SCALAR 

6 2 4 120 

4 9 + 3 12 REACH PAIR OF ITEMS IS ADDED 

1 21 

Here, APL applies the factorial ( I ) and addition (+ ) functions as if each item 
were a scalar argument. For factorial, each of the three items in the argument 
(a vector) returns a value. For addition, each corresponding pair of items is 
added. The results are just as if five statements had been entered as follows: 



6 

2 4- 
120 
7 

21 



13 
14 
15 

4 + 3 
9 + 12 



Monadic scalar functions take only one argument, which is placed immediately 
to the right of the function. The shape of the argument determines the shape 
of the result. For example, a scalar argument returns a scalar result, and a 
vector argument returns a vector result. 
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APL Primitive Functions 
1.1 Primitive Scalar Functions 

Dyadic scalar functions have two arguments that must conform to each other. 
They conform if one of the following is true: 

• Their shapes match. 

• At least one of the arguments is a singleton. 

When the shapes match, the function is applied a number of times equal to the 
number of items in the arguments, and the resulting array has the same shape 
as the argument arrays. 

Each item in the left argument array is associated with the item that has the 
same position in the right argument array, and the result is placed in that 
same position in the resulting array. For example: 

12 3+123 ^SHAPES OF BOTH ARGUMENTS CONFORM 

2 4 6 

aSHAPES do not conform 

12 3 + 1234 
10 LENGTH ERROR 

12 3 + 1234 

When one of the arguments is a singleton, the shape of the result is the same 
as the shape of the nonsingleton argument. Again, the function is applied on 
an item-by-item basis, but either the right or left argument (whichever is the 
singleton) is the same each time the function is applied. For example: 

1+12 3 nSINGLETON EXTENSION LEFT ARGUMENT 

2 3 4 

4 5 6 + 2 nSINGLETON EXTENSION RIGHT ARGUMENT 

6 7 8 

D *■ A *■ 10 (15 18 (8 4) 21) 30 
10 + + 30 

| 15 18 +---+ 21 j 

I |8 4| | 

I + — + I 
+ + 

5 + A 

15 + + 35 

| 20 23 + + 26 | 

I 113 9| | 
| +- — + | 
+ + 
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APL Primitive Functions 

1.1 Primitive Scalar Functions 

When both arguments are singletons, the shape of the result is the same as 
the shape of the argument with the higher rank. For example: 

B<-(1 1 1 p2) pB IS A RANK 3 SINGLETON 

Ml 1 p3) flC IS A RANK 2 SINGLETON 

D+B + C p SMALLER RANK WILL CONFORM TO LARGER 

D aDI SPLAY D, A SINGLETON OF SHAPE 111 
5 

The primitive scalar functions are pervasive functions; that is, their operations 
extend pervasively throughout the depth of enclosed arrays: 

RBOTH ARGUMENTS HAVE DEPTH = 3 
D <- A <- 10 (15 18 (8 4) 21) 30 
10 + + 30 

1 15 18 +— + 21| 

I 18 4| 1 

I +— + I 
+ + 

D <- B *■ 5 (12 11 (3 3) 2) 25 
5 + + 25 

| 12 11 +---+ 2| 
I 13 3| | 
I + — + I 
+ ■ + 

A - B 
5 + + 5 

|3 7 +---+ 19 1 
I 15 1| | 
I + — + I 
+ + 

The conformance rules for the arguments of the primitive scalar functions are 
also pervasive; APL does a conformance check at each level of enclosed arrays. 
During the check, APL performs singleton extension when necessary. The 
following example uses the dyadic minimum function ( L ), which returns the 
smaller of two arguments: 

4 (5 3) L (2 6) 1 

+ + + + 

12 4| |1 1| 
+ + + + 

In the preceding example, APL first pairs the corresponding items (through the 
process of scalar product). The pairs are 4 L ( 2 6 ) and (5 3 ) LI. Second, APL 
pairs the singleton argument with each element inside the enclosed arguments 
(through the process of singleton extension). These pairs are ( ( 4 L 2 ) ( 4 L 6 ) ) 
and ( ( 5 L l ) ( 3 L l ) ) . Finally, APL evaluates each pair of scalar arguments. 
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APL Primitive Functions 
1.1 Primitive Scalar Functions 

The following example shows two arguments that conform at the top level 
of their nesting, but do not conform at a lower level. This example uses the 
monadic enclose function (c ), which encloses its argument, as well as the 
dyadic minimum function ( L ). 

4 (5 3) L c 2 6 1 
10 LENGTH ERROR 

4 (5 3) [cHl 

In the preceding example, APL first pairs the corresponding items. The 
pairs are t L ( 2 6 l ) and ( 5 3 ) L ( 2 6 l ) . Second, APL pairs the singleton 
argument with each element inside the enclosed argument. These pairs are 
( ( 4- L 2 ) (<U6) (4LD). Third, APL recognizes the length error in the pair 
of enclosed arguments (5 3 and 2 6 l ) and signals the error. (If one of these 
enclosed arguments had been a singleton, APL would have applied singleton 
extension.) 

Primitive scalar functions generally take numeric arguments. The argument 
domain for relational functions (<,>,<,>,=,*), however, includes both 
character and numeric arguments. The equal (= ) and not equal O ) functions 
can take both character and numeric arguments in the same expression. The 
result domain for all primitive scalar functions is a scalar numeric array. 

Primitive scalar functions return empty arrays when there is an empty 
argument (provided that APL does not detect an error before evaluating the 
result). For example: 

1+2+3+ttiO niO ALWAYS GENERATES AN EMPTY ARRAY 

(APL outputs a blank line) 



<A<<< ' 



(APL outputs a blank line) 
^ARGUMENT SHAPES DO NOT CONFORM 



(1 3pl) + i5 
9 RANK ERROR 

(1 3pl) t i5 

A 

You can specify an axis ( [£] ) with dyadic scalar functions. For example, this 
allows you to apply a vector to each row or each column of a matrix. The 
general form of axis is as follows: AflKl B, where A and B are the arguments 
to f (a scalar function), and K is the axis argument. Note that K specifies the 
axes of subarrays constructed from whichever argument has the larger rank. 
The argument of smaller rank is combined with these subarrays. 
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APL Primitive Functions 

1.1 Primitive Scalar Functions 

For example, if you specify axes [13], then the shape of the subarrays of the 
larger rank argument is the lengths of that argument's first and third axes, 
and the smaller rank argument has the same shape as these subarrays. When 
APL combines the two arguments, it does so along the second axis of the larger 
rank argument of scalar extension. The length of the second axis in this case 
is the number of subarrays involved. 

In all cases, the axis argument must be near-integer in the vector domain. The 
length of K must be equal to the smaller of the ranks of the arguments, and 
the values in K must be between the index origin and the larger of the ranks 
of the arguments (you cannot specify an axis that does not exist). The order 
of the items in the axis argument makes no difference; however, K may not 
contain duplicates. The arguments to the function f must conform by having 
their shapes match along the axes specified by K. The shape of the result is the 
same as the argument with larger rank. 

For an enclosed argument, the application of the axis does not pervade, but 
works only at the top levels of nesting. See the following examples: 

A +■ 10 100 1000 aCREATE A 

□ *■ B *■ 3 4pil2 dCREATE AND DISPLAY B 

12 3 4 
5 6 7 8 
9 10 11 12 

A +[1] B hA CONFORMS TO AXIS 1 OF B 

11 12 13 14 
105 106 107 108 
1009 1010 1011 1012 

A +■ 1 10 100 1000 aCREATE NEW A 
A x[2] B a A CONFORMS TO AXIS 2 OF B 

1 20 300 4000 
5 60 700 8000 

9 100 1100 12000 

D +■ A +■ 2 3p0.1xi6 ^CREATE NEW A 
0.1 0.2 0.3 
0.4 0.5 0.6 

D i- B +■ 2 4 3pi24 aCREATE NEW B 
12 3 
4 5 6 
7 8 9 

10 11 12 

13 14 15 
16 17 18 
19 20 21 
22 23 24 
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APL Primitive Functions 
1 .1 Primitive Scalar Functions 



Q«-Z+-i4+[3 1]B 

1.1 2.2 3.3 

4.1 5.2 6.3 

7.1 8.2 9.3 

10.1 11.2 12.3 



ftORDER OF AXIS ARGUMENT UNIMPORTANT 
ftA CONFORMS TO AXES 1 AND 3 OF B 



13.it in. 5 15.6 

16.11 17.5 18.6 

19.t 20.5 21.6 

22. 4 23.5 24.6 



(\THE FOLLOWING SUBSCRIPTS DEMONSTRATE 
ft SUBARRAY COMBINATIONS USED BY APL 
nMATCH RETURNS 1 WHEN TRUE 





Z[;l;] = A + B[;l;] 


1 






Z[;2;] = A + B[;2;] 


1 






Z[;3;3 = 4 + fl[;3;] 


1 






Z[;4;] = 4 + B[;4;] 


1 





D +- -4 +■ 2 tpO.lxiS aCREATE NEW A 
0.1 0.2 0.3 . 4- 
0.5 0.6 0.7 0.8 

D <- Z +• A +[1 2] B f\A CONFORMS TO AXES 1 AND 2 OF B 

1.1 2.1 3.1 

4.2 5.2 6.2 

7.3 8.3 9.3 
10.4 11.4 12.1 



13.5 
16.6 
19.7 
22.8 



14.5 15.5 

17.6 18.6 

20.7 21.7 

23.8 24.8 



a THE FOLLOWING SUBSCRIPTS DEMONSTRATE 
ft SUBARRAY COMBINATIONS USED BY APL 



Z[ 

Z[ 



1] = 4 + B[ 

2] = 4 + B[ 
3] = 4 + B[ 



D +■ 4 +■ 4 3p0.1xil2 hCREATE MW A 
0.1 0.2 0.3 
0.4 0.5 0.6 
0.7 0.8 0.9 
1 1.1 1.2 
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1.1 Primitive Scalar Functions 

D «- Z <- A +[3 2] B M CONFORMS TO AXES 2 MZ) 3 OF B 

1.1 2.2 3.3 

4.4 5.5 6.6 

7.7 8.8 9.9 

11 12.1 13.2 

13.1 14.2 15.3 
16.4 17.5 18.6 
19.7 20.8 21.9 
23 24.1 25.2 

fiTHE FOLLOWING SUBSCRIPTS DEMONSTRATE 
a SUBARRAY COMBINATIONS USED BY APL 

Z[l;;] = A + B[l;;] 
1 

Z[2;;] = 4 + B[2;;] 
1 

PC+2 3p(i3) (t3) (i3) (2 3pi6) (2 3p 1 6 ) (2 3pi6) 

PC 
+ + + + + + 

|1 2 3 | |12 3| |1 2 3| 

+ + + + + + 

+ + + + + +■ 

|1 2 3 | | 1 2 3| |1 2 3| 

|4 5 6| |4 5 6| |4 5 6| 

+ + + + + + 

PC+1 
+ + + + + + 

|2 3 4| | 2 3 t| |2 3 H\ 

+ + + + + + 

+ + + + + + 

|2 3 4| 12 3 41 |2 3 4| 

|5 6 7| |5 6 7| |5 6 7| 

+ + + + + + 

PC + [2] 1 2 3 

+ + + + + + 

|2 3 4| |3 4 5| |4 5 6| 

+ + + + + + 

+ + + 1 + + 

|2 3 4| |3 4 5| |4 5 6| 
|5 6 7| | 6 7 8 | |7 8 9| 

+ + + + + + 

0+ER+l 2 (i3) 
1 2 + + 

|1 2 3| 

+ + 
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ftAXIS is not pervasive SO PLUS (+) 
a WITH AXIS APPLIES BETWEEN 
a +PC[2;3] AND t£J?[3] WHICH 
a IS A RANK ERROR 
PC+121ER 
9 RANK ERROR 
PC+121ER 

A 

The individual descriptions of the primitive scalar functions are presented 
in three sections. Section 1.1.1 describes arithmetic functions, Section 1.1.2 
describes logical functions, and Section 1.1.3 describes relational functions. 
Most of the individual descriptions include examples of how the functions 
work. 
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1.1.1 Arithmetic Functions 

The arithmetic functions, which are summarized in Table 1-1, perform well- 
known mathematical operations. All of them take numeric scalar arguments 
and return numeric scalar results. 

Table 1-1 Arithmetic Scalar Functions 



Monadic 




Dyadic 


Function 


Meaning 


Function 


Meaning 


+ B 


B 


A+B 




Add A to B 


-B 


Negative of B 


A-B 




Subtract B from A 


xfl 


Sign of B 


A*B 




Multiply A and B 


^B 


Reciprocal of B 


A±B 




Divide A by B 


*B 


e to the B th power 


A*B 




A to the B th power 


\B 


Magnitude of B 


A\ B 




A residue of B 


\B 


Ceiling of B 


A[B 




Maximum of A and B 


IB 


Floor of B 


AlB 




Minimum of A and B 


®B 


Natural logarithm of B 


A®B 




Logarithm of B to the base A 


: B 


Factorial of B 


Al B 




Binomial coefficient (number of 
combinations of B things taken A 
at a time) 


oB 


Pi times B 


AoB 




Trigonometric functions (B is in 
radians; see Table 1-2) 


?B 


Random integer from ; B 









1.1.1.1 + Conjugate 

The monadic + function returns a result that is the same as its argument; 
thus, + S is identical to B . For example: 



+ 5 

"5 

_+"l 2 "3 H ~5 
~1 2 "3 H "5 
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1.1.1.2 - Negative 

The monadic - function returns the negative of its argument; thus - B is the 
negative of B . Be careful not to confuse the negative function with the high 
minus sign (~ ) used to denote a negative number. For example: 



-1 2 3 
"12 3 4 
-"3 



1.1.1.3 x Signum 

The monadic x function identifies the sign of its argument; thus, x B is the sign 
of B . The signum function returns ~ l if the argument is less than 0, l if the 
argument is greater than 0, and if the argument is equal to 0. For example: 



x99 
x"5 



1.1.1.4 + Reciprocal 

The monadic * function returns the reciprocal of its argument; thus, * B is the 
reciprocal of B . For example: 



0.2 
0.5 



t5 
t2 



15 DOMAIN ERROR (DIVISION BY ZERO) 
4-0 



1.1.1.5 * Exponential 

The monadic * function raises the value of e (2.71828182845904523536...) 
to the power specified by its argument; thus, * B is e to the B th power. For 
example: 
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1 

*i 

2.718281828 

*10 
22026.46579 

*50 
5.184705529E21 



1.1.1.6 » Natural Logarithm 

The monadic ® function returns the natural logarithm of its argument; thus, 
® B is the natural logarithm (base e) of B . For example: 

91 



92.718281828459 
1 

922026.46579 
10 

®5.184705529£21 
50 

The ® symbol is formed with the o and * symbols. 

1.1.1.7 o Pi Times 

The monadic o function returns the product of its argument and the value of 
■k (3.14159265358979323846264...). For example: 

01 

3.141592654 

03 
9.424777961 

1.1.1.8 L Floor 

The monadic L function returns the greatest integer not greater than its 
argument, within a tolerance denned by Q CT. For example: 



~3 

4 
4 



L~2.5 

L4.111 

L4.999 
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Note that the D CT setting may affect the result of L . For example: 



UCT<-0 

IH. 9999999999 
H 

UCT<-1E~10 

14. 9999999999 
5 

The following is a formal description of how the floor function is implemented: 

VZ+-FL00R B ;QCI ;BXCT ;N 
[1] BXCT+UCT o DCT-K) 
[2] AN-(xB)x[.0.5 + |B 
[3] Z+N-(N-B)>BXCT Mf|l 
[4] 7 

1.1.1.9 r Ceiling 

The monadic r function returns the smallest integer not less than its 
argument, within a tolerance defined by Q CT. For example: 

T2.5 
2 

r^. in 

5 

fi.999 
5 

Note that the D CT setting may affect the result of r . For example: 

rt. oooooooooi 

5 

Dcr*-i£"io 

\n. 0000000001 

The r and L functions are related in the following manner: rs «--»-- l-B. For 
example: 

[t.lll 
5 

-r-4.in 
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1.1.1.10 | Magnitude 

The monadic | function returns the absolute value of its argument; thus, | S 
is the absolute value of B (that is, S= | B, if S> o and ( -B) = I B, if B< o). For 
example: 

|9 
9 

l"9 
9 

1.1.1.11 ; Factorial 

The ! of B (for integer arguments) is the product of the first B positive 
integers. For example: 

!2 
2 

!3 
6 

!5 
120 

If the argument to the factorial function is , the result is l . If the argument 
is a negative integer, APL signals DOMAIN ERROR. If the argument is not an 
integer, ! B is defined in terms of the mathematical function GAMMA as follows: 

\B -<-->- GAMMA (B+l) 

The : symbol is formed with the quote ( ' ) and period ( . ) symbols. 

For more information on the Gamma function, see Milton Abramowitz and 
Irene A. Stegun, eds., Handbook of Mathematical Functions with Formulas, 
Graphs, and Mathematical Tables (National Bureau of Standards, November 
1964), pp. 255-293; or John F. Hart, et al., Computer Approximations (Robert 
E. Krieger Publishing Company, 1978), pp. 130-136, 243-254. 

1.1.1.12 ? Roll 

When applied to an argument B , the monadic ? function generates an integer 
randomly selected from the integers i B (for a near-integer argument). For 
example: 
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?5 10 15 20 25 
H 1 8 6 25 

?5 10 15 20 25 

2 9 3 2 10 

A^2 3pt 6 

12 3 
4 5 6 

?A 
12 2 

3 5 5 

?A 
111 
3 3 6 



At the completion of the roll function, the value of Q RL changes: 



URL 
695197565 

?5 
H 

URL 
""1133752294 



If the argument is not a near-integer, or if a near-integer argument is less than 
the value of D 10, APL signals DOMAIN ERROR: 

□lO-i-l 

?0 
15 DOMAIN ERROR 
?0 

A 

UIO+0 
?0 


Note that the roll function is D IO-dependent: ? B when D 10 is l , is equivalent 
to (for the same value of QRL) 1+ ? B when Q 10 is o . 

The roll function is analogous to the rolling of several dice. Roll may generate 
duplicate values; thus, it differs from the dyadic deal function (?), which 
generates a set of unique random numbers. 
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1.1.1.13 +, -, x, and t- Addition, Subtraction, Multiplication, and Division 

The dyadic + , - , * , and + functions return the sum, difference, product, and 
quotient of their arguments, respectively. 

The right argument for the division function may not be unless the left 
argument is also . For example: 

0*0 

1 

1.1.1.14 * Power 

The dyadic * function raises the value of its left argument to the power 
specified by its right argument. For example: 

5*3 
125 

"5*3 
"125 

3*2.5 
15.58845727 
"3*2.5 
15 DOMAIN ERROR 
3*2.5 

A 

The power function's domain is restricted to the following combinations of 
arguments: 



Left 


Right 


Any 








>0 


> 


Any 


< 


Integer 



Note that 0*0 is l . 

If the right argument of the * function is exactly 0.5, APL returns the square 
root of the left argument. 
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1.1.1.15 ® Logarithm 

The dyadic ® function returns the logarithm of its right argument in the base 
of its left argument; thus, As B is the logarithm of B in base A . For example: 

10*1 


10*10 

1 

5810 
1.430676558 

Both arguments must be greater than zero. The left argument may not be l 
unless the right argument is also l . For example: l ® l is 1 . 

The ® symbol is formed with the o and * symbols. 

1.1.1.16 o Circle 

You use the dyadic o function to perform trigonometric functions. 

The left argument of o specifies which trigonometric function is to be 
performed. Only certain combinations of arguments are valid for the circle 
function. For arguments A and B , Table 1-2 lists the possible values of A 
(near-integer argument), and indicates the operation associated with each 

value. 

Table 1-2 Trigonometric Functions Performed by o 



a' 


Function 

( Z+AoB) 2 


Domain 


Result Domain 


"7 


arc tanhB 


1> | B 




~6 


arc cosh B 


B> 1 


Z>0 


"5 


arc sinhB 






"4 


(~ l+B* )*0. 5 


1< | B 


Z>0 


~3 


arc tan B 




( | Z) <o0. 5 


"2 


arc cos B 


1> I B 


( 0< Z) aZso 1 


"1 


arc sin B 


1> | B 


( | Z) SO0.5 





( 1-B*2) *0.5 


1> | B 


(Z>0)aZ< 1 


1 


sin B 




( | Z)<1 



1 The value of A must be a near-integer from 7 through 7 
The value of B is given in radians. 



(continued on next page) 
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Table 1-2 (Cont.) Trigonometric Functions Performed by 



Function 

4 1 ( z--AoB) 2 Domain 


Result Domain 


2 COS B 


( 1 Z)<1 


3 tanfi B* 2 | SvOO. 5 




4 ( 1+B* 2) *0.5 


Z> 1 


5 sinh B 




6 cosh B 


Z> 1 


7 tanh B 


( 1 Z)<1 


The value of 4 must be a near-integer from ~ 7 through 7 . 
The value of B is given in radians. 



1.1.1.17 L Minimum 

The dyadic L function returns the smaller of its two arguments. For example: 



M- L5 

4 

1 5 3L1 2 6 
12 3 

1.1.1.18 r Maximum 

The dyadic r function returns the greater of its two arguments. For example: 

5 

4 5 3 Tl 2 6 
4 5 6 

1.1.1.19 | Residue 

The dyadic | function returns the residue of the right argument with respect to 
the left argument. The residue is obtained by adding or subtracting multiples 
of the left argument from the right argument. The result of a residue operation 
takes the sign of the left argument. 

If the left and right arguments are equal, the residue is o . (Note that the 
residue function is □ CT-dependent.) If the left argument is , then the residue 
equals the value of the right argument. If the left argument is not , then the 
residue is in the range of the left argument through ; it may equal but may 
not equal the value of the left argument. For example: 
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5 1 8 

3 

-5 | 7 
3 

7 | 7 



7|0 


I 7 

7 

2 | 5 .8 

1.8 

1| 123.1567 
0.4567 

5 5 [8 8 
3 3 

5 5 5 1 2 
2 2 2 

5 | 2 2 2 
2 2 2 

A-<-3 0_~3_ 

B<-~6 "5 ~H "3 "2 "1 1 2 3 4 5 6 

Ao . |B 
0120120120120 
"6 "5 "4 "3 "2 "1 1 2 3 _H _5 6 
~2 "1 "2 "1 "2 '1 "2 "1 

1.1.1.20 : Combinations 

For arguments A and B , the dyadic ! function returns the number of 
combinations of B elements taken A at a time. For example: 

2U 
6 

10!10 

1 

For arguments A and B , the function's domain is described as follows: 

~ ( B< ) a ( ~ INTEGER B ) a ~ INTEGER A 

INTEGER is a function that returns l if all the items in its argument are 
integers, and otherwise. 

APL determines the result of the dyadic I function based on the algorithms 
explained in Table 1-3. The value l in the table for A , B , or B- A means that 
the argument or the difference between the arguments is a negative integer; 
the value means that the argument or the difference between them is not a 
negative integer. 
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Table 1-3 Determining Result for Dyadic i 



b-a Result 












( IB) -r ( M) x '.B-A 








1 








1 





APL signals DOMAIN ERROR 





1 


1 


( ~ 1*A) xAl A-B+ 1 


1 











1 





1 


Not a possible case 


1 


1 





( " 1*B-A) x ( | B+l) I ( \A+1) 


1 


1 


1 






Note that the dyadic I function is related to the mathematical function BETA 
as follows: 

BETA(A,B)<-+ vSx (A-l) '. A+B-l +•-»■ * A* (B-1)M+B-1 

The i symbol is formed with the ' and . symbols. 

For more information on the Beta function, see Milton Abramowitz and Irene 
A. Stegun, eds., Handbook of Mathematical Functions with Formulas, Graphs, 
and Mathematical Tables (National Bureau of Standards, November 1964), pp. 
255-293; or John F. Hart, et al., Computer Approximations (Robert E. Krieger 
Publishing Company, 1978), pp. 130-136, 243-254. 
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1.1.2 Logical Functions 

The monadic ~ (Not) and the dyadic a , v , * , and v functions (And, Or, Nand, 
Nor, respectively) are commonly called logical functions. The domain and range 
of logical functions are restricted to the Boolean values and 1. 

Table 1-4 is a truth table that shows the results of logical operations for 
arguments A and B . 

Table 1-4 Truth Table for Logical Functions 





Arguments 






Functions 






And 


Or 


Nand 


Nor 


Not 


A 


B 


A*B 


4vB 


A*B 


AvB 


~B 


A 


B 


A*B 


AvB 


A*B 


AvB 


~B 














1 


1 


- 





1 





1 


1 





- 


1 








1 


1 





- 


1 


i 


1 


1 








- 


- 





- 


- 


- 


- 


1 


- 


1 


- 


- 


- 


- 






The a symbol is formed with the a and ~ symbols. The v symbol is formed 
with the v and ~ symbols. 
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1.1.3 Relational Functions 

The dyadic <,<,=,*,>, and > functions are commonly called relational 
functions. The domain of relational functions is not restricted; they can take 
both numeric and character arguments. However, only the equal and not 
equal functions can have mismatched arguments, that is, one numeric and one 
character argument simultaneously. For example: 

M'=5 


' 5 ' =5 



The result domain of relational functions is restricted to the Boolean values 
and 1. A relational function returns the result l if true and if false. For 
example: 



9>6 
<C><A' 



When <,<,>, or > have character arguments, the order of characters in D A V 
is used as a collating sequence, and the evaluation is based on the respective 
positions of the arguments. When the relational functions have numeric 
arguments, the comparisons between the arguments are affected by the value 

of OCT. 

When you use relational functions with Boolean arguments, the relational 
functions can perform logical operations. For example, the not equal O ) 
function performs an exclusive OR operation if its arguments are s and l s: 

(0*0), (0*1), (1*0), 1*1 
110 

1.2 Primitive Mixed Functions 

The primitive mixed functions allow more extensive array manipulation 
than the scalar functions. Scalar functions take scalar arguments, return 
scalar results, and are extended to arrays on an item-by-item basis. Mixed 
functions are not as predictable. For example, depending on the values of their 
arguments, mixed functions may do the following: 
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Take a scalar argument and return a vector result: 



i 9 



123456789 

Take a vector argument and return a scalar result: 



i' 1231' 



1234 



Take a matrix argument and return a vector result: 



D+-B-H 3p 1 12 

12 3 

t 5 6 

7 8 9 

10 11 12 

,B 

1 2 3 4 5 6 7 8 9 10 11 12 



a CREATE AND DISPLAY B 



TRAVEL B (MAKE B A VECTOR) 



Table 1-5 summarizes the primitive mixed functions, which are described in 
this section. 

Table 1-5 Primitive Mixed Functions 

Meaning 



Function 


Name 


AlB 


Base 


+ B 


Branch 


A,B 


Catenate 


A,UC]B 


Catenate/ 


A T LK1B 


Laminate 


A 7 B 


Catenate 


A^B 


Contain 


A?B 


Deal 


=>B 


Disclose 


=>UGB 


Disclose 


d+B 


Drop 



Bases the representation of B in number system A . 

Modifies the standard order of execution in a user- 
defined operation. 

Catenates A to B along the last axis of A . 

Catenates/laminates A to B along the K th axis of A . 

Catenates A to B along the first axis of A . 

Determines whether all the items in array B are 
also found in array A . 

Deals A integers selected randomly in the range i B . 

Reduces the depth in an array. 

Discloses B and arranges the substructure axes (K ). 

For A> o, drops the first A items of B;for A< o, drops 
the last | A items of B . 

(continued on next page) 
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Table 1-5 (Cont.) Primitive Mixed Functions 



Function 



Name 



Meaning 



Ai IKJB 



c IK1B 

efl 

±B 

BB 
BLK1B 

A@B 
ABLK1B 
BLK1B 
SB 

*B 

AlB 

VB 

Y PCS 



4?B 

&B 

4 IK1B 

A&B 

i B 

AiB 



Drop For A> o, drops the first A items along the axes of 

B specified by K ; for A < o , drops the last | A items 
along the axes of B specified by K . 

Enclose Builds enclosed arrays. Returns a scalar containing 

B. 

Enclose Builds enclosed arrays; subarrays along axes K 

become scalars. 

Enlist Builds a simple vector with all of the simple scalars 

in its argument. 

Execute Executes the character string B . 

File Input Reads records from an external file into an APL 

workspace. 

File Output Writes information to an external file from an APL 

workspace. 



Format Formats array B . 

Format Formats character array B with width and precision 

specified by A . 

Grade Down Generates an index vector that can be used to sort B 

in descending order. 

Grade Down Generates an index vector that can be used to sort 

B in descending order, row by row or column by 
column. 

Grade Down Generates an index vector that can be used to sort B 

in descending order using collating sequence A . 

Grade Up Generates an index vector that can be used to sort B 

in ascending order. 

Grade Up Generates an index vector that can be used to sort B 

in ascending order, row by row or column by column. 

Grade Up Generates an index vector that can be used to sort B 

in ascending order using collating sequence A . 

Index Generates the first B consecutive integers from the 

Generator current index origin. 

Index Of Finds the first occurrence of B in vector A . 

(continued on next page) 
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Table 1-5 (Cont.) Primitive Mixed Functions 



Function 



Name 



Meaning 



AnB 



A=B 



ABB 


Matrix Divide 


EB 


Matrix Inverse 


AeB 


Membership 


A^B 


Pick 


,B 


Ravel 


,IK1B T IK1B 


Ravel 


AtB 


Represent 


ApB 


Reshape 


<J>B 


Reverse 


<!> CAT3S 


Reverse 


e IK1B 




eB 


Reverse 


A<t>B 


Rotate 


44> IK1B 


Rotate 


AelKlB 




AoB 


Rotate 


pB 


Shape 


A^B 


Subset 


A+B 


Take 


Af [K]B 


Take 



Intersection Returns a vector of the common items in the arrays 

A and B . 

Match Determines whether arrays A and B are identical in 

rank, shape, and value. 

Performs matrix division, solves linear equations, 
and finds a least-squares solution. 

Inverts the matrix B . 

Determines if A is a member of array B . 

Discloses an item from any depth of an array. 

Returns the ravel of B (makes B a vector). 

Merges or adds axes to the shape of B depending on 
the value of K . 

Represents B in number system A . 

Reshapes B to the shape specified by A . 

Reverses along the last axis of B . 

Reverses along the K th axis of B . 

Reverses along the first axis of B . 
Rotates by A along the last axis of B . 
Rotates by A along the K th axis of B . 

Rotates by A along the first axis of B . 

Returns the shape of B . 

Determines whether all the items in array A are 
also found in array B . 

For A > o , takes the first A items of B ; for A < o , takes 
the last | A items of B . 

For A > o , takes the first A items along the axes of 
B specified by K ; for A < , takes the last | A items 
along the axes of B specified by K . 

Transpose Transposes the axes of B (for a matrix, exchanges 

the rows and columns). 

(continued on next page) 
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Table 1-5 (Cont.) Primitive Mixed Functions 



Function Name Meaning 



A<s>B 


Transpose 


AuB 


Union 


vB 


Unique 


A~B 


Without 



Transposes the axes of array B according to A . 

Returns a vector of the items in the arrays A and B . 

Removes the duplicate items of array B . 

Returns a vector of the items of array A that are not 
found in array B . 
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i Base 



j_ Base 
Form 

A±B 

Left Argument Domain 



Type 




Numeric 


Shape 




Any 


Depth 




or l (simple) 


Right Argument 


Domain 


^pe 




Numeric 


Shape 




Any 


Depth 




o or l (simple) 


Result Domain 






Type 




Numeric 


Rank 




0r - 2+(pp4)+ppB 


Shape 




( ~ 14- pA) , 14- pS 


Depth 




o or l (simple) 


Implicit Arguments 




None. 






Description 







The dyadic i function (known as base or decode) reduces a representation in 
a number system to a value. More specifically, it converts to decimal those 
vectors along the first axis of the right argument that are expressed in the 
positional number bases of radices given by vectors along the last axis of the 
left argument. 

The base function is best explained as the converse of the represent function 
(t ). The following example shows the two functions operating on a quantity 
expressed in yards, feet, and inches: 
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ol YARD, 2 FEET, 3 INCHES IS 63 INCHES 



1760 3 12ll 2 3 
63 

1760 3 12T63 

12 3 

The expressions At B and AlB differ only in the value included in B; A expresses 
the number base in both cases. 

The number of items in both arguments, for example A and B, must generally 
be the same; the first item in A expresses the radix in which the first item in 
B is decoded, and so on. However, if A is a singleton, it is extended so that its 
length is the same as that of the first axis of B . For example, the following 
expression has the effect of producing the base 10 value of the base 8 number 
3777 (octal-to-decimal conversion): 

8 13 7 7 7 
2047 

For arguments A and B , the argument arrays for x must conform to one of the 
following rules: 

• A or B is a scalar. 

• The results of ~~ l + p A and ltpS are equal. 

• Either ~ 1+ p 4 or 1+pB equals 1. 

If the argument arrays conform to the last rule, the axis that equals 1 is 
extended to match the appropriate other axis. For example: 

(2 3p5)l(3 4p3) 
93 93 93 93 
93 93 93 93 

(2 3p5)l(l 4p3) 
93 93 93 93 
93 93 93 93 

(2 lp5)i(3 4p3) 
93 93 93 93 
93 93 93 93 

The following are some other uses of the base function: 
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a CONVERT 3 YDS. 2 FT. 4 IN. TO INCHES 
1 3 12 l 3 2 H 
136 

^DETERMINE IF 2.5 IS A ZERO OF THE POLYNOMIAL 
fl ((6xI*2)-(7xX))-20 
2.5x6 7 ~20 


nBXSE 10 EQUIVALENT OF BASE 5 JVC/MBFi? 
511- 3 M. 
119 

You can use the base function to evaluate polynomials; the expression X± C 
evaluates a polynomial in X with coefficients given by the vector C . 

For vectors A and B , the base function can be thought of as a form of the 
inner product operator. The expression Ax B is equal to W+ . x B, where W is the 
weighting vector (W-<-$ x\ - i+(M,l) given by the expression W[pj4]-«-+ l, and 
Wl ( -N) +p4] is equal to A [ ( -AT) + lp4] *J/[ ( -tf) + l+p4] . The value of 
ALU is irrelevant. The following example shows two equivalent operations: 

X+1760 3 12 
B*-i 2 3 
AlB 
63 

36 12 l+.xB 
63 

Note that if the right argument is empty, the type of the left argument is not 
significant: 



o o 










(3 2 lp'4')i 



(3 2 lpO)i 10 
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Possible Errors Generated 

10 LENGTH ERROR ( LENGTHS OF INNER AXES DO NOT MATCH) 

15 DOMAIN ERROR ( ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR ( INCORRECT TYPE) 

27 LIMIT ERROR ( FLOATING OVERFLOW) 

2 7 LIMIT ERROR ( VOLUME TOO LARGE) 
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-*■ Branch 
Form 

Argument Domain 



iy pe 


Near-Integer 


Shape 


Any 


Depth 


or l (simple) 


Result Domain 




None. 




Implicit Arguments 




None. 




Description 





The monadic -»■ function (known as branch) modifies the standard order of 
execution in a user-defined operation. 

Normally, APL lines in operations are executed in the order of their line 
numbers; execution begins at the first line following the operation header 
and ends with the last line in the operation. Branch changes the sequence of 
execution by transferring control to another line in the operation. 

There are two types of branches: unconditional and conditional. Unconditional 
branches specify the next line to be executed. The result of an expression 
evaluation determines the next statement in a conditional branch. 

Unconditional branches consist of a branch symbol (-»- ), followed by a 
representation of the number of the operation line to which you want to 
transfer control. The argument can be a label, a constant, a variable, or 
an expression. Its value (or, if it is a vector, the value of its first item) is 
equivalent to an integer line number within the current definition. Execution 
continues at that line. 
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Conditional branches can be expressed in one of the following three forms: 
• -* line-number x i logical-expression 

Here APL evaluates the logical expression that is the right argument 
of i . The logical expression returns either a l (true) and the control 
passes to the specified line or a o (false) and the control passes to the next 
statement. (This form only works when DIO"-o.) In the following example 
a simple counter controls the number of times the statements in a loop are 
executed. The example branches to line number 0, an out-of-range number, 
and forces an exit from the operation: 



• 





V COUNTER 




[1] 


U--' NUMBER OF ENTRIES:' 


o JHQ 


[2] 


C-i-0 




[3] 


LOOP: +0xiC=N 




[<0 


C«-C+l 




[5] 


■+L00P 




[6] 


V 





-^logical-expression I line-numbers 

This type of conditional branch specifies several line numbers and 
associated logical expressions as possible branch destinations. Control 
passes to the line number corresponding to the first logical expression that 
evaluates to 1 (true). For example: 

VF A 
[1] +{A>0)/3 

[2] 'WILL NOT ACCEPT NEGATIVE NUMBERS' o -+0 
[3] 'FUNCTION CONTINUING NORMALLY' 

F 5 
FUNCTION CONTINUING NORMALLY 

F "2 
MILL NOT ACCEPT NEGATIVE NUMBERS 
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-^-line-numbers IK1 

Here the value of K is used as an index to select the corresponding line 
number. For example: 

7 labs 
[1] K*-2 
[2] ■+{LAB1,LAB2,LAB3)IK1 



LABI IS EXECUTED' o -K) 
LAB2 IS EXECUTED' o +0 
LAB 3 IS EXECUTED' o +0 



[3] LABI 
[>] LAB2 
[5] LABZ 
[6] V 

LAB5 
LAB 2 IS EXECUTED 

Note that -*■ is described in greater detail in Chapter 3 of the VAX APL User's 
Guide along with other information on user-defined operations. 

Possible Errors Generated 

7 SYNTAX ERROR ( BRANCH NOT ALLOWED IN MIDDLE OF AN EXPRESSION) 

11 VALUE ERROR ( BRANCH HAS NO RESULT) 

15 DOMAIN ERROR ( ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR ( INCORRECT TYPE) 

1 5 DOMAIN ERROR ( NOT AN INTEGER ) 

2 7 LIMIT ERROR ( INTEGER TOO LARGE) 
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, and t Catenate/Laminate 
Form 

A,B A.ZK1B A T B AjIKIB 

t is formed with , and - 



Left Argument 


Domain 


Type 


Any 


Shape 


- 


Depth 


Any 


Right Argument Domain 


Type 


Any 


Shape 


- 


Depth 


Any 



Result Domain 



Type 

Rank l r ( p p A ) TppB (for catenate) or 

1+ ( p p A ) rppB (for laminate) 

Shape - 

Depth ( s a ) r = B 



Implicit Arguments 

None. 

Description 



The dyadic APL function joins together the specified axis of two arrays. If, for 
A , [K~\ B or A 7 [if] B, K is a near-integer, the function is called catenation, and 
A and B are joined along the K th axis. If K is not a near-integer, the function 
is called lamination, and A and B are joined along a new axis lying between 
the axes named by ]_K and \ K. The forms A , B and A T B represent catenation 
and join the arrays along their last or first axis, respectively. 
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If one of the arguments is a scalar, its length is extended to match the shape 
of the other argument. If both arguments are scalars, the result is a two-item 
vector. For example: 

5,6 ^CATENATE 2 SCALARS, RESULT IS A VECTOR 

5 6 

B<-2 3p 1 6 

B,[l]7 ^CATENATE SCALAR TO FIRST AXIS OF B 

1 2 3 
4 5 6 
7 7 7 

B,7 ^CATENATE SCALAR TO LAST AXIS OF B 

12 3 7 
4 5 6 7 

For catenation, the arguments' ranks must differ after scalar extension by at 
most 1. Note that a singleton argument is not extended to conform to the other 
argument: 

r\CATENATE SINGLETONS OF DIFFERENT RANKS 
(1 lp7),l 1 1 lp8 
9 RANK ERROR (RANKS DIFFER BY MORE THAN ONE) 
(1 lp7),l 1 1 lp8 

A 

nTRY AGAIN 

D +■ R *■ (1 lp7), 1 1 lp8 
7 8 

pR 
112 

In the following example, two arrays of equal rank are catenated. The shapes 
of the arguments match except for the axis [ ( K ) ] along which the arrays are 
being joined: 

B-<-3 4 5pl2 

PB 
3 4 5 

C-t-3 6 5pl4 

PC 
3 6 5 

iKB,[2]C 

PR 
3 10 5 

Note that B is equal to R [ ; it;] and C to R [ ; 4-+ i 6 ; ] . 
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The next example shows the catenation of two arrays whose ranks differ by 1. 
Again, the shapes of the arguments match except for the axis along which the 
arrays are being joined: 

fl+3 4 5pl2 

pB aB IS RANK 3 

3 4 5 

C+H 5p33 

pC fiC IS RANK 2 

4 5 

R+B,[1]C ^CATENATE ALONG FIRST AXIS OF B 



PR 
i+4 5 



^ATTEMPT TO CATENATE ALONG SECOND AXIS 



B,[2]C 
10 LENGTH ERROR {SHAPES OFF AXIS DO NOT MATCH) 
B.L21C 

A 

Here, B is equal to R [ i 3 ; ; ] and C to R [ 4 ; ; ] . 
The following are more examples of catenation: 

A+5 8 9 

fl-6 7 

A,B ^CATENATE TWO VECTORS 

5 8 9 6 7 

10, A, B, 12 
10 5 8 9 6 7 12 

'NAME' ,'XY' 
NAMEXY 

B<-2 3pl 2 3 4 5 6 aCREATE B 

C+2 3p7 8 9 10 11 12 aCREATE C 

B 
12 3 
4 5 6 

C 
7 8 9 
10 11 12 

B,[1]C PiCATENATE ALONG FIRST AXIS 

1 2 3 

4 5 6 

7 8 9 

10 11 12 

B,[2]C (^CATENATE ALONG SECOND AXIS 

12 3 7 8 9 
4 5 6 10 11 12 
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Q<-B<-2 3 3p<SSSTTTUUUVVVWWWXXX' 



B T C a USE COLUMN CATENATE 

12 3 

4 5 6 

7 8 9 

10 11 12 

B,C ^CATENATE ALONG SECOND AXIS 

12 3 7 8 9 
4 5 6 10 11 12 

D-*-A+2 3 3p<ABCDEFGHIJKLMN0PQR' 
ABC 
DEF 
GUI 

JKL 
MNO 
PQR 

SSS 

TTT 

uuv 

vvv 
www 

XXX 

ABCSSS 
DEFTTT 
GHIUUU 

JKLVVV 
MNOMW 
PQRXXX 

Note that the catenation of scalars produces a vector: 

ppt,5 
1 

For lamination (A , [ K] B and A T LK1 B where K is not a near-integer), the 
arguments must have the same ranks and shapes after singleton extension. 
The following are examples of lamination: 

nCREATE NEW DIMENSION BEFORE THE FIRST 
b DIMENSION WHEN [Z]<1 
Q<-X<-MBC' , [0.5]' D£F' hADD A ROW 
ABC 
DEF 

pX 
2 3 



A,B ^CATENATE RANK 2 OBJECTS 
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AD 
BE 
CF 

3 2 



AB 
CD 
EF 

UV 

wx 

Yl 



AB 
CD 
EF 



aCREATE MEW DIMENSION AFTER THE FIRST 
a DIMENSION WHEN l<[Jf]<2 
U+X+'ABC ,[1.3] <DEF< a ADDA COLUMN 



QX 



D«-£^3 2p' ABCDEF' 



U*-F<-3 2p<UVWXYZ< 



U*-R<-E,l.2]F 



nNOW TRY EXAMPLE WITH HIGHER RANK OBJECTS 
uNOTE THAT APL RESHAPES EACH ARGUMENT 
a BEFORE JOINING 



a CREATE NEW DIMENSION BEFORE THE FIRST 
fl DIMENSION WHEN [#]<1 
a ADD A PLANE 



UV 
WX 
Yl 

2 3 2 



PR 



U<-R<-E,ll.9]F 



AB 

UV 



^CREATE NEW DIMENSION AFTER THE FIRST 

fl DIMENSION WHEN 1<[Z]<2 

fiADD A ROW, PREVIOUS ROWS BECOME PLANES 



CD 
WX 

EF 
Yl 

3 2 2 



PR 
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^CREATE NEW DIMENSION AFTER THE SECOND 
A DIMENSION WHEN 2<[A:]<3 
f\ADD A COLUMN, PREVIOUS COLUMNS BECOME ROWS 



D<-i?*'£,[2.3]F 



AU 

BY 

CW 
DX 

EY 
El 

3 2 2 



Pi? 

rTRY EXAMPLE USING SINGLETON EXTENSION 
D<-i?<-E,[.5]'Z' fiADD A PLANE 



AB 
CD 
EF 

11 
11 
11 



PR 



2 3 2 

D«-J?<-E,[1.5] <X< 
AB 
XX 



CD 
XX 

EF 
XX 

qR 
3 2 2 

<Y< ,[2.5]£ nADD A COLUMN 

YA 

YB 



YC 
YD 

YE 
YF 



aADD A ROW, PREVIOUS ROWS BECOME PLANES 



Note that if □ 10 <-->- 0, then . 5 is valid as the axis value for lamination. This 
is the only case in which an axis may take a negative argument (range: ~ i< K). 



APL Reference Manual 1-39 



Primitive Mixed Functions 

, and T Catenate/Laminate 

Further examples: 

□+il+-(0 CAB')) 

+-- + 
\AB\ 

+-- + 

+-+ 

hi 
+-+ 

0-K>" 

(APL outputs a blank line) 
U+MAXi-2 3 p A 1 '4B' B C 
+ + 1 

|0 +--+I 

1 \AB\\ 
I +--+I 
+ + 

+--+ t — + +-+ 

MB I I+-+I I I 

+--+ I hi I +-+ 
I+-+I 

+ — + 
MAX, [l]fl ^CATENATE ALONG FIRST AXIS 

+ + 1 

|o +--+I 
I MB! I 

I +--+I 

+ + 

+--+ + — + +-+ 

\AB\ |+-+| | | 

+--+ I hi | +-+ 

I+-+I 

+ + 

+-+ +-t +-+ 

hi hi hi 
+-+ +-+ +-t 

Q+D+0 'DP' 
+--+ 
\DP\ 
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D, [21 MAX ^CATENATE ALONG SECOND AXIS 

+ + 1 

|0 +~+| 
I \AB\\ 

+ + 

+--+ +--+ + — + +-+ 
\DP\ \AB\ I+-+I I I 

+--+ +--+ i hi i +-+ 
+ — + 

fiSHOW CATENATION OF TWO ARRAYS WHOSE RANKS DIFFER BY 1 
pMAX 

2 3 

Q+VIC+B.D 
+-+ +--+ 
\H\ \DP\ 
+-+ +--+ 

pVIC 
3 

Q*W*-MAX, [1] VIC 

+ + 1 

|0 +--+| 
I \AB\\ 
I +--+I 

+ + 

+--+ +---+ +-+ 

\AB\ |+-+| I I 

+--+ I l<H I +-+ 

I+-+I 

+ + 

+-+ +--+ 

hi \dp\ 

+-+ +--+ 

pW 

3 3 



n+x+n , c , i 

4 + - + 

111 
p* 

2 

B 
+-+ 

hi 
+-+ 

PB 



aSHOW LAMINATION 



(APL outputs a blank line) 
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D+M,[0.5]B 
H +-+ 

HI 

+-+ 
+-+ +-+ 

hi hi 
+-+ +-+ 

2 2 

D<-z«vr,[i.9]fl 

4 +- + 

hi 

+-+ 
+-+ +-+ 

in hi 
+-+ +-+ 

PZ 
2 2 

Possible Errors Generated 

9 i?4M ERROR 

9 i?4M: £i?i?Oi? (RANKS DIFFER BY MORE THAN ONE) 

10 LENGTH ERROR (SHAPES OFF AXIS DO NOT MATCH) 
15 DOMAIN ERROR (INCORRECT TYPE) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 

2 8 AXIS RANK ERROR (NOT VECTOR DOMAIN) 

30 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 

30 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 

3 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 
30 AXIS DOMAIN ERROR (INCORRECT TYPE) 

29 AXIS LENGTH ERROR (NOT SINGLETON) 

3 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) 
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=> Contains 
Form 



=> is formed with => and 



Left Argument Domain 



Type 



Type 


Any 


Shape 


Any 


Depth 


Any 


Shape 


Any 


Depth 


Any 


UUIIIdlll 

Type 


Boolean 


Rank 





Shape 


i (scalar) 


Depth 


(simple scalar) 



Implicit Arguments 

D CT (determines comparison precision) 

Description 

The dyadic £ function determines whether the left argument contains all the 
items found in the right argument. The result is a Boolean scalar: true, if 
the left argument is a superset of the right argument, and false if it is not. 
Duplicate items in either argument do not affect the result. For example: 

4*3 tp 23 5M- 98 3t 98 t7 98 32 78 65 12 23 
A 2 B-<-ilOO 


B o A 
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The 2 function compares items in terms of the match O ) function, which uses 
the value of D CT. Because = allows mixed-type arguments, you can compare 
characters with numbers. However, such a comparison is always false, so that 
if you use mixed-type arguments for dyadic = , the result will be zero. For 
example: 

'23 21 25' £ 22 23 24 25 26 


Further examples: 

U+URL+0 >AB< (c,3) 

+--+ + + 

\AB\ |+-+| 
+--+ M3|| 

+ + 

Q+P00L+2 2 p <AB< 'EB< (c,3) 
+--+ 
\AB\ 

+--+ + + 

\EB\ |+-+| 
+--+ I 1311 

+ + 

POOL 2 URL 
i 

U+VAN+0 'QTN< "1 (c,3) 

+ + 1 + + 

\QTW\ |+-+| 

+— + I I3|| 

I+-+I 

+ + 

D+7IC+-(c,if),o,(CDP') 
+-+ +--+ 

1*1 \DP\ 

+-+ +--+ 

VAN o VIC 


Possible Errors Generated 

None. 
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? Deal 
Form 

A?B 

Left Argument Domain 



Type 


Nonnegative near-integer 


Shape 


Singleton 


Depth 


o or l (simple) 


Right Argument 


Domain 


Type 


Nonnegative near-integer 


Shape 


Singleton 


Depth 


o or l (simple) 


Result Domain 




Type 


Nonnegative integer 


Rank 


l 


Shape 


A 


Depth 


l (simple) 



implicit Arguments 

URL 10 (A?B when QIO *■ l is identical to l + A?B when 010 *■ o for the 
same QRL) 

Description 

For A ?B, the dyadic ? function generates a vector of integers randomly selected 
from x B; no number is selected more than once. The length of the result vector 
is specified by A . For example: 
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5?5 
4 2 3 15 

5?1.0£7 
2047059 8326627 1771140 853115 3809508 

5?1.0£7 
8895125 7387197 6272379 6940437 9062050 

5?1.0£7 
6693744 185074 2861354 853279 5088023 



Unlike the roll function, dyadic ? is analogous to dealing a number of cards 
from a deck with no two cards alike. Roll is analogous to rolling several dice 
independently; roll may generate duplicates, but deal will not. 

The value of the system variable Q RL affects the result of the deal operation, 
and the value of D RL changes each time a deal operation completes 
successfully. For more details about Q RL , see Chapter 2. 

Possible Errors Generated 



9 RANK ERROR {NOT SINGLETON) 

10 LENGTH ERROR (NOT SINGLETON) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

15 DOMAIN ERROR (NEGATIVE NUMBER NOT ALLOWED) 

15 DOMAIN ERROR (RIGHT ARGUMENT IS LESS THAN LEFT) 

27 LIMIT ERROR (INTEGER TOO LARGE) 
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= Depth 
Form 

Argument Domain 



Type 


Any 


Shape 


Any 


Depth 


Any 



Result Domain 



Type 


Integer (non-negj 


Rank 





Shape 


i o (scalar) 


Depth 


(simple scalar) 


Implicit Arguments 




None. 





Description 

The monadic = function (known as depth) indicates the maximum level of 
nesting in an array. A simple array has 1 level of nesting (0 if the array is 
scalar). An enclosed array has a depth of at least 2. 



Examples: 



D^9 



^CREATE A SIMPLE SCALAR 





aCREATE A SIMPLE ARRAY 

OO'ram ARE YOU GOING? 1 
WHERE ARE YOU GOING? 

= C 
1 
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D+D+l (5 6 7) 11 12 ftCREATE AN ENCLOSED ARRAY 

1 + + 11 12 

15 6 7| 

+ + 

»D 
2 

nCREATE AN ENCLOSED ARRAY WITH MORE NESTING 
□+E+1 (5 6 7 (8 9 10)} 11 12 
1 + + ii 12 

|5 6 7 + +| 

I |8 9 10 | | 

| + +| 

+ + 

*E 

3 



Possible Errors Generated 

None. 
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=> Disclose 
Form 

=>B =>[K]B 

Argument Domain 



Type 


Any 


Shape 


Any 


Depth 


Any 


Result Domain 




Type 


Same as constituent items in B 


Rank 


(ppB) + tr/p"p*"( ,B) ,c+B 


Shape 


(pB) , + r/(p"( ,B) ,a+B)~<= tO 




(pZ)[,JJ]+-*+r/(p"(,B)~e l O 


Depth 


or~i+ = B 


Implicit Arguments 




None. 





Description 



The monadic => function reduces the depth of an array. It reverses the building 
action of the monadic enclose (<= ) function. Disclose is the left inverse of enclose 
(B++^^B andB^=> [#] c ZK1B) . 

The rank of the items in B must be the same (singleton items are extended). 
However, the lengths of the corresponding axes do not need to match. For 
example, three enclosed items of shape 1 3 1, 2 6 2, and 4 2 4 match in rank, 
but not in shape. When the shapes do not match, each item is padded along 
each axis, and the length of each of the result's axes is equal to the longest 
corresponding axis among the items of B . In the preceding example, the 
portion of the result that corresponds to the three items would have the shape 
4 6 4: 
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rALL items same ram 

F*(3 2pi6) (2 Zp'ABCDEF') (2 UplO 4> 1 9 ) (5 lp'lWXf' 
PF 

p"F 

+ — + + 1 + — + + + 

13 2| |2 3| |2 4| |5 1| 
+ + + + + + + + 

U+DD<-?F nHOTE fill items 

12 
3 4 

5 6 



ABC 
D E F 



2 3 4 5 

6 7 8 9 







T 
U 
V 
X 
Y 

pDD 
H 5 4 

Disclose only reduces one level of enclosure: 

i4<-(<=i3) 'ABC 3 

A 

+ + + + 3 

I+---+I \ABC\ 

||1 2 3| | +---+ 

|+ +| 

+ + 

pA 
3 

=A 
3 
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++ 

II 
++ 



P A 
+ -+ + + 
|3| II 
+ -+ + + 

X^A 
I 



+ + 

|1 2 3| 

+ + 

A 
3 

3 3 



+ + + + 

| | I I 

+ + + + 

B C 





Disclose with axis (form 3 [if] B) allows you to specify the placement of the 
disclosed item's axes. The number of axes specified by K must be equal to the 
rank of the items of B (ignoring the singleton items), and the axis numbers 
must be less than the sum of the rank of B plus the rank of the items of 
B (i (ppB)+t r\ ,p"p"B). The axis numbers must also be unique. The 
following example shows various combinations of axis arguments and the 
resulting arrays: 



R *■ (3 3pi9) (2 3p'0JV' 
R 

+ + + + 

| 1 2 3 | I+--+ +--+ +--+I 

|4 5 6| | | Off | \TI\ \MA\ | 

|7 8 9| J+--+ +--+ +--+J 

+ + | + — + + __ + + -- + | 

||ffO| \IT\ | M| | 

+ + 

A+oR 
=A 



<TI< 'MA' 



'NO' 



'IT' 'AM') 
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A 
1 2 3 

^ 5 6 

7 8 9 



+--+ + --+ +--+ 
I Off | |n | |JM| 
+--+ +--+ +--+ 

Iffoi |ir| |M| 
+--+ +--+ +--+ 
+--+ +--+ +--+ 

I ! I I I I 
+--+ +--+ +--+ 

B<-=[1 2]K 
B 

1 +--+ 
|0ff| 

2 +-- + 
\TI\ 

3 + -- + 
I AM I 

U +-- + 
\K0\ 

5 +-- + 
\IT\ 
+-- + 

6 +-- + 
\AM\ 

7 + -- + 

I I 
+ -- + 

8 +-- + 

I I 
+ --+ 

9 + — + 
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3 

=B 
2 

PA 

2 3 3 

pB 

3 3 2 

C<o[l 3] J? 

s(7 
2 

PC 
3 2 3 

C 
1 2 3 

+--+ +--+ + — + 
| Off | in | \MA\ 
+--+ +--+ +--+ 

H 5 6 

+--+ +--+ +--+ 

|JV0| | XT | | M| 

+--+ +--+ +--+ 

7 8 9 

+--+ +--+ +--+ 

1 I I II I 
+--+ +--+ +--+ 

D-<o[2 3] J? 
=0 
2 

PD 

2 3 3 
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D 

12 3 



+--+ +--+ +--+ 
|0ff| \TI\ \MA\ 
+--+ +--+ +--+ 
+--+ +--+ +--+ 
|JV0| \IT\ \AU\ 
+ -- + +--+ + -- + 
+--+ +--+ +--+ 

+--+ +--+ +--+ 
F*3[2 11 R 
E 

1 +--+ 

Off | 
+ -- + 

4 +--+ 
\N0\ 

7 + — + 

I I 
+ -- + 

2 +--+ 

\ti\ 

5 +-- + 

liri 

8 +-- + 

I I 
+ -- + 

3 +-- + 
| AM | 

6 +--+ 
\AM\ 
+-- + 

9 +-- + 

I I 
+ -- + 
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2 

p£ 

3 3 2 

F«[3 1]R 

= F 
2 

pF 
3 2 3 

F 
14 7 

+--+ +--+ +--+ 

1 Off | |ffO| I I 
+--+ +--+ +--+ 

2 5 8 
+--+ +--+ +--+ 

ini \n\ l l 

+--+ +--+ +--+ 

3 6 9 
+--+ +--+ +--+ 

1 AM I I M| | I 

+--+ +--+ +--+ 
C«[3 21 R 
sG 

2 

pG 

2 3 3 

G 
14 7 



+--+ +--t + — + 

1 0*1 l«0| I I 

+--+ + --+ +--+ 

+--+ +— + +--+ 

in I Hi 7 ! t 

+--+ +--+ +— + 

+--+ + — + +--+ 

\MA\ \AM\ I I 

+--+ +— + +--+ 
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If all the items of B are scalars, then the axis, if specified, must be empty: 

T<-c"(i3)(iH)(i5) 

T 

+ + + + + + 

|+ + | | + + | | + + | 

111 2 3 M 11123411 | |1 2 3 4 5| | 

|+ +| |+ +| |+ +| 

+ + + + + + 

3 

3 

= "T 
2 2 2 

p"T 

++ ++ ++ 

II II II 
++ ++ ++ 

+ + + + + + 

| 1 2 3 [ |1 2 3 4| |1 2 3 4 5| 

+ + + + + + 

=S 
2 

PS 
3 

The disclose of an array which contains only scalars and empty arrays as item 
will be an empty array: 

£f-2 " 3 
E 
2 ++ 3 

II 
++ 

=E 



PE 
fE 
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X 



(APL outputs a blank line) 



=X 
1 

OX 
3 

« 




The following expression describes the formal relationship between disclose 
and disclose with axis: =B<-+ =[(ppS) + ipp+ B]B 

(Possible Errors Generated 



9 RANK ERROR (ITEMS NOT SINGLETON OR ALL THE SAME RANK) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 

2 8 AXIS RANK ERROR (NOT VECTOR DOMAIN) 

2 9 AXIS LENGTH ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 

3 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 
3 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 

30 AXIS DOMAIN ERROR (DUPLICATE AXIS NUMBER) 

3 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

30 AXIS DOMAIN ERROR (INCORRECT TYPE) 

3 AXIS DOMAIN ERROR (NOT AN INTEGER) 

3 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) 
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+ Drop 


i Drop 




Form 




A+B A + IKJ B 


Left Argument Domain 


Type 

Shape 

Depth 


Near-integer 
Vector domain 
o or l (simple) 


Right Argument Domain 


Type 

Shape 

Depth 


Any 
Any 
Any 


Result Domain 




Type 
Rank 
Shape 
Depth 


Same as right argument 

( p ,a) rppfl 

r ( p B ) - | A (if no explicit axis) 

= B 


Implicit Arguments 




None. 




Description 





The dyadic + function builds an array by dropping a specified number of items 
from an existing array. The left argument specifies how many items are to be 
dropped from each axis in the right argument array. Thus, for A 4- B, item A [ K~\ 
is used to drop values along the K th axis of B . 

Unless the right argument is a scalar, the left argument must have a number 
of values equal to the rank of the right argument (for arguments A and B , 
p , A must equal p p S). For instance, if the right argument is a vector, the left 
argument must have just one value. If that value is positive, APL drops the 
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4- Drop 

specified number of items from the beginning of the vector; if the value is 
negative, APL drops items from the end of the vector. For example: 

2+ i 5 

3 "+ 5 

~2+i5 
12 3 

If the right argument is a scalar, it is reshaped to a singleton with a rank 
equal to the length of the left argument. 

If the rank of the right argument is greater than 1, the result array is said to 
be a "corner" of the argument array. The origin of the corner is determined by 
the signs of the items of the left argument. For example, if the right argument 
is a matrix, there are four possible corners, as shown in Figure 1-1. 

The drop function leaves a corner that is diagonally opposite to the origin 
specified by the signs of the items of the left argument. In the following 
example, note how the order of the signs determines the "corner" selected from 
the matrix: 



1 2 3 
4 5 6 
7 8 9 

9 

1 

3 

7 



Q^03 3 pi9 

2 2 + C 
"2 "2 iC 
"2 2 + C 
2 ~2 +C 



Note that for arguments A and B , the dimension of the remaining corner is the 
complement of A with respect to p B, or | (pB)-i. 

If the value of an item in the left argument is greater than the length of the 
corresponding axis, then, for arguments A and B , A 4- B returns an empty array 
with shape r ( P B ) - I A. 

If the left argument is empty, the right argument must be a scalar, and the 
result is the right argument. 

When you use + with an axis argument, K is a vector of axis numbers whose 
lengths are determined by corresponding items of the left argument, A . 
Formally, + with an axis argument can be described by the following: 

Z *■ 0>pS o Z[JG <- A o I *■ Z\B 
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The value for K must be in the vector domain, and each item must be a near- 
integer in the set ippfl. Therefore, the values of K are QIO dependent. The 
items may be in any order, but they may not be duplicated. The length of K 
must be less than or equal to the rank of the right argument, and it must 
match the length of the left argument. 

The value for K does not have to specify all the axes in B . APL regards the 
lengths of any missing axes as zero. This means that you can drop rows or 
columns of a matrix without specifying zero for the length of the other axis. 
For example: 





Q+A 


.«-8 5pi40 


1 2 


3 


4 5 


6 7 


8 


9 10 


11 12 


13 


14 15 


16 17 


18 


19 20 


21 22 


23 


24 25 


26 27 


28 


29 30 


31 32 


33 


34 35 


36 37 


38 


39 40 




3 Kl] A 


16 17 


18 


19 20 


21 22 


23 


24 25 


26 27 


28 


29 30 


31 32 


33 


34 35 


36 37 


38 


39 40 




"2 


+ [2] A 


1 2 


3 




6 7 


8 




11 12 


13 




16 17 


18 




21 22 


23 




26 27 


28 




31 32 


33 




36 37 


38 






3 4 


+ [2 1] A 


24 25 






29 30 






3"+ 35 






39 40 








QIO 


* 




4 3 


+ [0 1] A 


24 25 






29 30 






34 35 






39 40 







aDROP 3 ROUS OF A 



nDROP THE LAST 2 COLUMNS OF A 



hDROP 4 ROWS, 3 COLUMNS OF A 



fiDROP 4 ROWS, 3 COLUMNS OF A 
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Further examples: 



U+POL+2 3pO,(c'4BC'),l,0,(cMB'),' ' 
+---+ 1 

\ABC\ 

t + 

+— + 

\AB\ 

POL 
+---+ 1 
\ABC\ 

+ + 

+--+ 
\AB\ 
+ --+ 

2 nilPOL 

(APL outputs a blank line) 
"1 illlPOL 

+---+ 1 
\ABC\ 

+ — + 

2 l[2]P0£ 
1 


U+MEW^H 3 p'll' 1 3 (c,l) ~2 << <A< < ' 1 HO 
+ -- + 1 3 

liri 

+---+ "2 ++ 

I+-+I II 

IUII + + 

I+-+I 

+ — + 

A 

1 HO 

1 "1 4- MEW 
+---+ ~2 

I+-+I 

mil 
1+-+1 
+ — + 

A 

1 ~H 

2 1 + [2 l]«ffl 

+ + 

II 
+ + 
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2 i MEW 
A 

1 ~H 



The following expression describes the formal relationship between drop and 
drop with axis: A+B ■*-->■ 44-Cipp B] B 

Possible Errors Generated 



9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (LEFT LENGTH NOT EQUAL TO RIGHT RANK) 
15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 

2 8 AXIS RANK ERROR (NOT VECTOR DOMAIN) 

2 9 AXIS LENGTH ERROR (LEFT ARGUMENT HAS WRONG LENGTH) 

3 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 
3 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 

30 AXIS DOMAIN ERROR (DUPLICATE AXIS NUMBER) 

30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

3 AXIS DOMAIN ERROR (INCORRECT TYPE) 

30 AXIS DOMAIN ERROR (NOT AN INTEGER) 

3 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) 
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c Enclose 
Form 

<^B c [£] B 

Argument Domain 



Type 


Any 


Shape 


Any 


Depth 


Any 


Result Domain 




Type 


Same as constituent items 


Rank 


( PPB) -p ,K 


Shape 


(pS) [( rppB)~Kl 


Depth 


( 0*=B) +=B 


Implicit Arguments 




None. 




Description 





The monadic <= function builds enclosed arrays. For a nonsimple scalar 
argument, the result of the form <= B is always an enclosed scalar item. If the 
argument is a simple scalar, the depth remains the same: B^ + <^B when B is a 
simple scalar. The result of the form <= [Jf] B is an array of enclosed scalars: 
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B *■ 1 

C «- i5 

C +• 2 2 p MBCT' 

[]+B+cB ^ENCLOSE A SIMPLE SCALAR, NOTHING HAPPENS 
4 

U*-B-^,B flMilXS A SINGLETON 

+- + 

M 
+-+ 

□<-£>•= c 

+ + 

1 1 2 3 4 5 j 

+ + 

□«-D<-cD 
+ -- + 
\AB\ 
\CD\ 

pfl o pC » pD nTHE NEU B C AND D ARE SCALAR 

(APL outputs 3 blank lines) 



Each time you use monadic c , you increase the depth of the argument by one 
(unless the argument is a simple scalar). For example: 

U+D+-2 2p 'ABCD' 
AB 
CD 

PD 
2 2 

=i> hDEPTH OF D SHOWS A SIMPLE ARRAY 

1 

U+D+cD 

\AB\ 
\CD\ 

PD 

(APL outputs a blank line) 
=D hDEPTH OF D HAS INCREASED TO 1 

2 

Using the catenate function ( , ) with <= allows you to create arrays with 
multiple items. In such an expression, you must use parentheses to prevent 
the scope of <= from extending to the rightmost end of the expression. You can 
also enclose arrays that are already enclosed. The only limit to the depth you 
create is the memory available to the workspace. 
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For example: 



B<-4 
Oi5 

Q<-E*-B , (cB) , cC *N0TE USE OF PARENTHESES 

H n + + 

|12 3 4 5| 

+ + 

3 

2 

n<-2 2 p '4BCD' 

U+E+B , (cB) , (cC) , D nNOTE USE OF PARENTHESES 

4 u, + + +--+ 

|i 2 3 4 5 | |AB| 

+ + \CD\ 

+ -- + 

QE 
4 

=E 
2 

U+E+cE 
+ + 

1^ n + + + __ + | 

| |12 3 4 5| MB | | 
| + + | CB || 

I + --+I 

+ + 

pE fiSHAPE OF E SHOWS IT IS NOV A SCALAR 

(APL outputs a blank line) 

=E 
3 

The result of the form c [ K ] B is in an array of items formed by enclosing 
subarrays along the axes given by K . The axis numbers in K must be a unique 
set of numbers in ippfl: 

<-S<-2 3pi6 

t + 

U 2 3| 

|4 5 6| 
+ + 
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c[l]S 

+ — + + — + + — + 

|1 H\ |2 5| |3 6| 

+ + + + + + 

c[2]S 

+ + + + 

| 1 2 3 1 \H 5 6| 

+ + + + 

=[1 2]5 

+ + 

|1 2 3| 
It 5 6| 
+ + 

c[2 1]S ^CHANGING AXIS ORDER TRANSPOSES SHAPE 

+ + 

|1 H\ 

12 5| 

13 6| 
+ + 

SCHILLER*-' AGAINST' 'STUPIDITY' 'THE GODS' 'THEMSELVES' 
Q+-SCHILLER+-3 2pSCHILLER,' CONTEND' 'IN VAIN' 
+ + + + 

\ AGAINST \ \ STUPIDITY] 

+ + + + 

+ + +■ + 

\THE G0DS\ | THEMSELVES] 

+ + + + 

+ + + + 

\ CONTEND \ \IN VAIN] 
+ + + + 

Qi-PHRASESi-7 [ 1 . 5] c [2 ] SCHILLER 
+ + 

1+ + + +1 

\] AGAINST] | STUPIDITY \\ 

1+ + + +1 

+ + 

+ + 

|+ + + +| 

| \THE GODS] | THEMSELVES] | 

1+ + + +1 

+ + 

+ + 

1+ + + +1 

| | CONTEND | | IN VAIN \ | 

1+ + + +1 

+ + 

p PHRASES 
3 1 
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If K is empty, than it has no effect if B is a simple array. If B is enclosed, 
then each item in B becomes enclosed one level deeper (<=[ i 0] B -<-->- c " B). For 
example: 

[>S-<-2 3p6 a CREATE S, A SIMPLE ARRAY 
12 3 
it 5 6 

c[iO]S fiEMPTY K, NO CHANGE 

1 2 3 
4 5 6 

SCHILLER^' AGAINST* 'STUPIDITY' 'THE GODS' 'THEMSELVES' 

U+SCHILLER+3 2p SCHILLER, 'CONTEND' 'IN VAIN' 
+ + + + 

\ AGAIN ST \ | STUPIDITY] 
+ + + + 

+ + + + 

\THE G0DS\ | THEMSELVES ] 
+ + + + 

+ + + + 

| CONTEND | \IN VAIN] 

+ + + + 

c[ i0] SCHILLER nEMPTY K, ITEMS NESTED DEEPER 

+ + + + 

|+ +| |+ +| 

| \ AGAINST M I I STUPIDITY | | 

1+ +1 1+ +1 

+ + + + 

+ + + + 

| + +| |+ +| 

| \THE GODS] | | \ THEMSELVES] \ 

1+ +1 1+ +1 

+ + + + 

+ + + + 

1+ +1 1+ +1 

| | CONTEND] | | | Iff VAIN] \ 

1+ +1 1+ +1 

+ + + + 

Further examples: 
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U+POL+2 3 p <ABC< (c,2) 99 M' '0' 

+ + + + 

\ABC\ I+-+I 
+— + I 1211 

+ + 

99 4 

cPOL 
+ + 

I+---+ +---+I 

\\ABC\ |+-+| 

l+— + I 1211 

I I+-+I 

| +— + 

199 A 



The first two of the following expressions describe the relationship between <= 
and <=[#]. The third expression describes the relationship between c [ K ] and 
the disclose (=> [ #] ) function: 

cB ■*-*■ c[ ipp B]B 

c[X]B ■«-»■ c(4^)^B (only true when K includes all axes of B ) 

B <-► d[^] c[Z] B 



Possible Errors Generated 

2 7 IIWIJP ERROR {INTEGER TOO LARGE) 

2 8 AXIS RANK ERROR (NOT VECTOR DOMAIN) 

30 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 

3 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 
30 AXIS DOMAIN ERROR (DUPLICATE AXIS NUMBER) 

30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

3 AXIS DOMAIN ERROR (INCORRECT TYPE) 

3 AXIS DOMAIN ERROR (NOT AN INTEGER) 

30 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) 
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e Enlist 
Form 



efl 



Argument Domain 



Type 


Any 


Shape 


Any 


Depth 


Any 


Result Domain 




Type 


Same as argument 


Rank 


i 


Shape 


Vector 


Depth 


l (simple vector) 


Implicit Arguments 




None. 





Description 

e builds a simple vector by recursively raveling each of the items in its 
argument. For example: 

U+A+e (2 (2 2p5 6 7 8)) 'ABC 'A' 2 5 6 7 8 'ABC 
2 5 6 7 8 ABCA 2 5 6 7 8 ABC 

Possible Errors Generated 

None. 
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± Execute 




Form 




S.B 




± is formed with i and ° 


Argument Domain 




Type 


Any 


Shape 


Any (Vector domain for characters) 


Depth 


Any (o or l for characters) 


Result Domain 




iy pe 


Any 


Rank 


Any 


Shape 


Any 


Depth 


Any 


Implicit Arguments 




None. 




Description 





The monadic i function executes the expression represented by its character- 
string argument as if that expression were entered in immediate mode or 
included in a user-defined operation. For example, the expressions i 5 and 
i ' i 5 ' return the same result: 



15 
12 3 15 

!' i5' 
12 3 4 5 

B«-i5 
i.'B< 
2 3 4 5 
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For a numeric argument B , ±B returns B . For example: 

«20 
20 

B«-i5 

i.B 
1 2 3 f 5 

For an enclosed or heterogeneous array B , ±B returns B . For example: 

± 1 2 'A' 3 
12 4 3 

Q-<-P0i>2 3p ('ABC') (c,2) 99 'A' 

+ + + + 

\ABC\ I+-+I 
+ — + II2II 

I+-+I 

+ + 

99 A 

i. 'POL' 

+ + + + 

\ABC\ |+-+| 
+ — + l|2|| 

I+-+I 
+ — + 

99 A 

i POL 

+ + + + 

\ABC\ |+-+| 
+ — + Il2|| 

+ + 

99 A 

The ± function is similar to the UXQ system function; however, there are 
several differences. 

One difference is that the UXQ system function always returns a value, but 
the i function returns a value only if the evaluation of its argument returns 
a value. Another difference is that the QXQ function cannot execute a branch 
function (■+ ), and the ± function can. 

The i and D^O functions also handle errors differently. Errors resulting from 
the evaluation of the Q XQ function's argument cannot be trapped; if an error 
occurs during the evaluation of its argument, QXQ returns an empty array 
whose shape indicates the number of the error. With the 4 function, however, 
you can use □ TRAP to trap errors. If an error occurs in the character string 
being executed by ± , APL generates — in addition to the normal three-line error 
message — an execute error message for the line on which the actual execute 
error occurred. 
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For example: 

V GRIFF A 
[1] B-t-iX 
[2] 7 

GRIFF ' 3 , ' 
7 ± SMTM mOK (RIGHT ARGUMENT TO FUNCTION MISSING) 
3, 

A 

25 EXECUTE ERROR 
GRIFF [1] B+±4 

A 

)5I 
Gi?IFF[l] * 
B 
11 ML(7£ ERROR 
B 

A 

GJ?IFF' ' 
11 VALUE ERROR (REQUIRED VALUE NOT SUPPLIED BY EXECUTE) 
GRIFF 11] Bt-iA 

A 

In the previous example, when the argument to the ± function was invalid 
( ' 3 , ' ), APL generates six lines of error messages and suspends operation 
execution. The blank argument is a valid one for the ± function, but t ' ' does 
not produce a value, so APL signals VALUE ERROR when the assignment is 
made to B . 

If you enter the attention signal while the i function is executing, APL stops 
and signals ATTENTION SIGNALED. 

Note that quiet functions are still quiet when executed, provided that the 
execute is the leftmost function in the statement. When the argument is empty 
and numeric, the result is an empty numeric vector (± i0 <-+ i o). When the 
argument is empty and character, the result is an empty character vector ( ' ' 
•*-->- i ' ' ) if a value is required by the expression. For example: 
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,±'Z<-1' 

i. lO 

A 



oQUIET, ffO OUTPUT 



(APL outputs a blank line.) 



Possible Errors Generated 

9 RANK ERROR (NOT VECTOR DOMAIN) 
2 5 EXECUTE ERROR 
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B and @ File Input and Output 
Form 

B K[mode | index]]\ chan frdata-type~i 
is formed with Q and +- 

Argument Domain 



type 


Numeric 


Shape 


Vector domain 


Depth 


Any 


Result Domain 




Type 


Any 


Rank 


Any 


Shape 


Any 


Depth 


Any 



Form 



[dataj \[[mode | index\l\ chan \[data-typej 
is formed with Q and ■+■ 



Left Argument Domain 



Type 


Any 


Shape 


Any 


Depth 


Any 


irgumer 


it Domain 


Type 


Numeric 


Shape 


Vector domain 


Depth 


or l (simple) 
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Result Domain 



Type 


Same as left argument 


Rank 


p p data-sent 


Shape 


p data-sent 


Depth 


= data-sent 


Parameters 





mode 

Is an integer representing one of the modes listed in Table 5-3 in the VAXAPL 
User's Guide. This parameter is used only when accessing files with ASCII 
sequential organization. When you specify mode, it must be surrounded by 
brackets. 

index 

Is the component number, record number, or key value in a direct-access, 
relative, or keyed file, respectively. Index must be surrounded by brackets. 

chart 

Is a positive integer scalar whose value is a channel number in the range 1 
through 999. 

data-type 

Specifies the data type of the record you want to read or write. When you 
include a value for data-type, you imply that the record contains pure data; 
that is, the beginning of the record does not contain any header information. If 
you do not specify data-type, or if you specify a value of , APL assumes that 
there is a header at the beginning of the record 

data 

Is the data that is to be written to the file. 

Description 

The file input (B ) and file output (0 ) functions are for reading and writing files. 
B and B are described in greater detail in Chapter 4 of the VAXAPL User's 
Guide along with other file I/O information. 

The file output function (B ) in its monadic form deletes a component or 
record from a direct-access, relative or keyed file. APL signals DOMAIN ERROR 
(DELETION NOT ALLOWED) if you use monadic B with a sequential file. When 
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monadic S is not the leftmost function in the statement, it returns an empty 
numeric matrix of shape 7 5. 

The value of the B function is the record read from the specified file. The B 
function is quiet. It does not display a result if it is the leftmost function in a 
statement. When it is not the leftmost function, B returns the value of its left 
argument. 

When a B or B function references a channel associated with a file that is not 
open, APL opens the file and executes the function. 

Possible Errors Generated 



15 DOMAIN ERROR {DELETION NOT ALLOWED) 
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t First 
Form 



+ B 



Argument Domain 



Type 


Any 


Shape 


Any 


Depth 


Any 


Result Domain 




Type 


Same as selected item 


Rank 


Same as selected item 


Shape 


Same as selected item 


Depth 


Same as selected item 


Implicit Arguments 




None. 





Description 

The monadic + function builds an array by disclosing the first item from an 
existing array. If B is empty, then + returns the prototype of B : 



B <- 4 

C *■ i5 

D *■ 2 2 p 'ABCD' 

tD 
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+ First 



D <- E *■ B , (cC) , cD 

t + + +--+ 

|12 3 15| \AB\ 

+ + \CD\ 

+-- + 
+£ nFIRST OF E 

"+ 

= + £ aDEPTH SHOWS A SIMPLE SCALAR ARRAY 



t£[2] nFIRST OF SECOND ITEM OF E 

12 3 4 5 

= + E[2] flDJfPffl SflOI/S A SJ^PIS AFX4Y 



1 

5 

AB 
CD 

1 

2 2 







p+£[2] AS&4P2 SflOJ/S A VECTOR 

t£[3] fiFJPSr OF THIRD ITEM OF E 

s+E[3] flMPfff SflCWS 4 5IWPIF 4i?J?4r 

P+BT.3] aSJMPF, SffCWS 4 M^rail 

+ 3p99 aEMPTY ARG RETURNS PROTOTYPE 

t ' ' ^PROTOTYPE IS A CHARACTER BLANK 
t 0p(l 2 3) 'jIBC 



For simple arrays, the result of monadic + is the same as it would be with 
the dyadic take function (+ ) when all the items of the left argument are 1 . 
Formally, this can be represented as follows: + B «--»■ ( (ppfl)pi)tS. However, 
note that take does not disclose items of an array. First is also related to the 
pick (=> ) function as follows: + B -*--► (c(ppB)pi)3B 

Possible Errors Generated 

None. 
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¥ Monadic Format 
Form 

* is formed with t and 

Argument Domain 



Type 


Any 


Shape 


Any 


Depth 

HArnoin 


Any 


Type 


Character 


Rank 


l r p P B for simple numeric or heterogeneous B 




ppB for simple character B 




2 for nonsimple B 


Shape 


(~ 1+ pB )■<->■ (~ 14- presult) for simple B 


Depth 


1 (simple) 



Implicit Arguments 



D PP (Determines decimal precision) 

n NG (Determines minus sign placement) 

DDC (Displays control of enclosed arrays) 



Description 



The monadic ▼ function formats its argument array as a character array, 
making it look as it would appear when displayed by APL. 

Thus, if the argument array is already of type character, the result is identical 
to the argument: 
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0+A<-3 bp'STAH SAM STEVE' 
STAN 
SAM 
STEVE 

STAN 

SAM 

STEVE 

p?4 
3 5 



If the argument array is of type numeric, the result appears to be identical to 
the argument; however, the blank characters displayed along with the items 
are actually part of the result array. For example: 



A+2 4pi8 

A 
12 3 4 
5 6 7 8 

PA 
2 4 

B 
12 3 4 
5 6 7 8 

Pfl 
2 7 

(' ',B)[;2xi4] 
1234 
5678 



Note the difference between the shapes of the numeric array A and the 
character array B . 

Since it is not feasible to indicate both shape and depth in a two-dimension 
display, the format of an enclosed array is always a matrix. Shape is indicated 
by blank lines in the same manner as for simple arrays. Display of depth is 
controlled by UDC, the display control system variable. 

Further examples: 

U+POL+2 3p ('ABC') (c,2) 99 'A' 

+ — + t 1 

\ABC\ |+-+| 

+---+ l|2|| 

I+-+I 

+ + 

99 A 

pPOI 
2 3 
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D<-B<-tP0L 

+ — + o + — + 

\ABC\ |+-+| 
+— + I I2|| 

+ — + 
99 A 

pB aTHE SHAPES OF B AND POL ARE DIFFERENT 

6 13 

U+XT+ 3 p (2 p 5) (") (iO) ^CREATE AN EMPTY ARRAY 
++ ++ ++ 

I! I! II 
1 1 ++ ++ 

++ 

pXT 
3 

U+B+iXT 
++ ++ ++ 
II II II 
I I ++ ++ 
++ 

P B 
i\ 8 

Possible Errors Generated 

None. 
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j Dyadic Format 
Form 

AjB 

j is formed with t and ° 

Left Argument Domain 

Type Near-integer 

Shape Vector domain 

Depth o or l (simple) 

Right Argument Domain 

Type Numeric 

Shape Any 

Depth o or l (simple) 

Result Domain 

Type Character 

Rank l r p p B 

Shape ( ~l+pfl) ,+/l o/(2,ro.5xp,A)p J 4 

(provided no widths are ) 

Depth l (simple) 

Implicit Arguments 

ONG (determines minus sign placement) 

Description 

The dyadic ▼ function formats its right argument according to the width and 
precision information supplied by its left argument. 

The left argument generally contains one pair of numbers for each column (last 
axis) in the right-argument array. The first number specifies the width of the 
field; the second number controls the print precision. For example: 
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U+B+2 4pi8 
12 3 4 
5 6 7 8 

4<-5 2 4 14 6 3 
R^AlB 
R 
1.00 2.0 3 4.000 
5.00 6.0 7 8.000 

PR 
2 19 

Because the right argument has four columns, the left argument (A ) has four 
pairs of numbers. The last axis of the formatted array (R ) has a length of 
19, the sum of the widths specified in A (5+4+4+6). The second number of 
each pair in A specifies how many digits are to be displayed to the right of the 
decimal point. 

You do not have to specify more than one pair of numbers as the left argument. 
If you specify only one pair, that pair is replicated a number of times equal to 
the length of the last axis of the right argument. 

The last axis of the formatted array Y , below, has a length of 3 6 because the 
format function specifies that each of the three columns should have a width of 
12. The items are displayed with four digits to the right of the decimal point 
because the second number of the left argument pair is 4 . 

Note the difference in the results when the array is formatted so that all 
columns have a width of 9 and a print precision of 2 , and then a width of 6 
and a print precision of o . 

If a print-precision specification in the left argument is negative, the associated 
item is formatted in scientific rather than decimal form, and the argument 
represents the number of digits in the item's mantissa. 

OJM 3p 31.16 "1.07 "15.578 8 "235.61 
31.16 1.07 

"15.578 8 "235.61 

pX 

2 3 

07*-12 hjX 

31.1600 0.0000 1.0700 
"15.5780 8.0000 "235.6100 

pY 
2 36 

4-f-9 2fX 
A 
31.16 0.00 1.07 
"15.58 8.00 "235.61 
PA 
2 27 
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D^J?-<-6 Ofl 
31 1 

"16 8 "236 

PR 

2 18 

D<-fl-<-9 "2tI 
3.l£l O.OJfO 1.1F0 

"1.6£1 8.0E0 '2.HE2 

Q+C+7 ~lfX 
JE1 020 _1E0 
~2E1 8E0 "2E2 

The width specification in the left argument may be omitted or may be . If 
it is omitted, the entire left argument must be a singleton and is extended to 
(2x _ i+pS)pO,i4,for arrays A and S . If the width specification is , then 
APL uses the minimum width possible, allowing for one blank between the 
formatted columns. 

Two more examples of dyadic v follow. The first illustrates the formatting of a 
rank 3 array; the second shows how you can use ¥ to format tables. 

D-M<-2 2 2pi8 

1 2 

3 t 

5 6 
7 8 

D-K>5 2t4 

1.00 2.00 

3.00 4.00 

5.00 6.00 
7.00 8.00 
PC 

2 2 10 

D->-B-<-3 3p 100101111 
1 
10 1 

1 1 1 



1 tB 



100 
101 

111 
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Second example: 

fiTABLE FORMATTING 

R0US+-5 7p' APL FORTRANCOBOL BASIC PLI ' 

COLS*-' USERS PROGS SYST 

F0RM+-5 3p4 

( (7f ') -R0HS),C0LS 1 7 OjFORM 
USERS PROGS SYSTS 
APL 12 3 

FORTRAN 4 5 6 

COBOL 7 8 1 

BASIC 2 3 4 

PLI 5 6 7 

If the right argument to the dyadic format function is empty, the shape of the 
result is determined by the following function: 





VZH EMPTY SHAPE R ;C;W;P 


[1] 


L-(ri + pJ?),2)p((l=p,L)/0),L 


[2] 


U*-Ll;U 


[3] 


P-L[;2] 


[t] 


Otf, (P+3),2,6,[1.5]6-P 


[5] 


Z<-((/=0)x2+(-xP)+<"l 


[6] 


C<-(Z<K)[;il 


[7] 


Z-«-("Hp/?),(-(/[l]=0)++/C 


[8] 


V 


For< 


example: 




p5 2*0 2p5 


10 






pO 2 5 0T0 2p5 


9 





Possible Errors Generated 

9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

15 DOMAIN ERROR (NEGATIVE NUMBER NOT ALLOWED) 
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15 DOMAIN ERROR {WIDTH TOO SMALL) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 

2 7 LIMIT ERROR (PARAMETER OUT OF RANGE) 
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t Monadic Grade Down 

Form 

ts yc«s 

y is formed with v and I 

Argument Domain 

Type Homogeneous 

Shape Matrix, vector, or scalar (not singletons of rank >2) 

Depth o or l (simple) 

Result Domain 

Type Nonnegative integer 

Rank 1 

Shape ( <t>pfl) LK1 

Depth 1 (simple) 

Implicit Arguments 

010 (IB when ,010 *■ l is identical to l + f B when ,010 + o) 

Description 

The monadic f function returns a numeric vector whose items can be used to 
sort the items of the argument in descending order. Thus, grade down does not 
actually sort arrays. It creates a permutation vector of the index numbers of 
the argument array's items, and this vector can then be used to sort the array. 

Sorting a vector requires two steps. First, the vector is the argument to the 
grade down function, and then the result is used to index the vector: 

A+2 9 7 i+ 3 10 H 

0*-B*-U 
6 2 3 4 7 5 1 

AIB1 
10 9 7 % H 3 2 
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If two or more items of a vector or matrix have the same value, the order of 
the items is determined by their relative positions in the original array (this 
is called a stable sort). For character arguments, the collating sequence is 
determined by the value ofQAV. Note that for numeric arguments, the result ii 
not D CT-dependent. 

When you use the grade down function to sort a matrix, APL treats each row 
or column as a string. Thus, you can use the function to sort row by row or 
column by column, but not to sort individual items within a row or column. 
When applied to a matrix, the grade down function produces a vector whose 
length is equal to the number of rows or columns in the matrix. 

The following sorts the matrix B by rows and then sorts the matrix by columns 

D«-B<-3 5p 321503197032080 
3 2 15 
3 19 7 
3 2 8 

fB 
13 2 

?[2]B 
13 2 

3 2 15 
3 2 8 

3 19 7 

?[1]B 

4 1 2 3 5 

B[;?[1]B] 

5 3 2 10 

7 3 19 

8 3 2 

In this example, the original first row remains the first row, the third row 
becomes the second row, and the second row becomes the third row. Note that 
f B and t C 2] B are equivalent. 

You can also sort character arrays by rows or by columns. For example: 
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D+-B<-3 bp'ALLENALAN ALLAN' 
ALLEN 
ALAN 
ALLAN 

6[fB;] 
ALLEN 
ALLAN 
ALAN 

B[;Ul]B] 
NLLEA 
LANA 
NLLAA 

If the argument to 1 is a scalar, the ravel function is applied to extend it to a 
one-item vector, and the result of the f function is ,QIO: 

R 

1 

ppR 
l 

Note that CT is not an implicit argument to the grade down function. 

Possible Errors Generated 



9 RANK ERROR (NOT A SCALAR, VECTOR, OR MATRIX) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 

2 8 AXIS RANK ERROR (NOT VECTOR DOMAIN) 

29 AXIS LENGTH ERROR (NOT SINGLETON) 

3 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 

30 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 
30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

3 AXIS DOMAIN ERROR (INCORRECT TYPE) 

3 AXIS DOMAIN ERROR (NOT AN INTEGER) 

30 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) 
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f Dyadic Grade Down 

Form 

AfB 

y is formed with V and 

Left Argument Domain 



Type 


Character 


Shape 


Any 


Depth 


or 1 (simple) 


irgumer 


it Domain 


Type 


Character 


Shape 


Any 


Depth 


or l (simple) 



Result Domain 



Type 


Nonnegative integer 


Rank 


l 


Shape 


1+PtB 


Depth 


l (simple) 



Implicit Arguments 

010 (Ay B when ,010 ■*- l is identical to i+A^B when ,010 +■ o) 

Description 

The dyadic f function returns a numeric vector whose items can be used to 
sort the items along the first axis of the right argument in descending order. 
(The sort is performed according to the collating sequence defined in A .) Grade 
down does not actually sort arrays; it creates a permutation vector of the index 
numbers of the argument array's items, and this vector can then be used to 
sort the array. If either argument is empty, the result of the grade function is 
i ltpB. If the length of the first axis of B is one, then the result is ,010. 
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If two or more items of the right argument have the same value, the order of 
the items is determined by their relative positions in the original array (this is 
known as a stable sort). 

Sorting an array requires two steps. First, the array is the right argument 
to the grade function, and then the result is used to index the array. The 
left argument determines the order in which APL collates the items of the 
right argument; APL evaluates the collating sequence from right to left. For 
example: 



ALPHA1+- 


' I VXL CDM ' o ff <- ' CMXI VCILI 


X +- □ <- 


ALPHAiyN 


2 16 8 3 5 1+ 


1 9 


sai 




MCCLXVIII 




DATES+-QBOX 'MCCLXVIII 


VII 




MLXXIII 




DCCCXXIII 




CLXVI 




MDCLIII 




CLXXI 




XVIII' 




X + n +■ 


ALPBA11 DATES 


6 13 1+758 


2 


DATE SIX: 


;] 


MDCLIII 




MCCLXVIII 




MLXXIII 




DCCCXXIII 




CLXXI 




CLXVI 




XVIII 




VII 




HEX+' Q123H5S783ABCDEF' 


RD+BBOX 


'8£7 


3DA 




976 




AES 




F8 




305 




HO' 
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X *- <- flfflfflfl 
4 3 12 6 5 7 

4£8 
976 
8E7 
354 
3£>5 

F8 

40 

To sort an array that contains more than one font, you can use sequences 
similar to the following, depending on the desired result: 

flZ SORTS AFTER I AND BEFORE Y 

ALPHA2+'AABBCCDDEEFFGGHHIIJJKKLLMMNN00PP 

QgRRSSTTUUVVWWXXYYZZ ' 

W0RDS+-UB0X 'HOPE 
NASAL 
REEL 
HELM 
HEEL 
NEST 

NEAR 
PALM' 

X +■ D <- ALPHA2W0RDS 
8 7 2 6 3 5 4 1 

WORDS IX;] 
PALM 
NEAR 
NASAL 
NEST 

Mil 
HEEL 
HELM 
HOPE 

flZ SORTS AFTER A AND BEFORE Y 

ALPHA3+'ABCDEFGHIJKLMN0PQRSTUVWXYZABCDEFGHIJKL 
MNOPgRSTUWXU ' 

X +■ D +■ ALPHAdfl WORDS 
72358641 

WORDSLX;] 
NEAR 
NASAL 

MIL 
HEEL 
PALM 
NEST 
HELM 
HOPE 
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If any items appear in the right argument when they have not been specified 
in the left argument, APL considers them equal and places them at the end of 
the sort sequence. For example: 

ALPHAS' ABCDEFGHIJKLMNOPQRSTUVUXYZ' 

GAMES+UBOX 'FREEZE TAG 
MONOPOLY 
CHESS 

HIDE AMD SEEK 
BACKGAMMON 
FRISBEE' 

X <- D <- ALPHAH1GAMES 
2 3 4 6 5 1 

GAMES [X -J 
MONOPOLY 
CHESS 

HIDE AND SEEK 
FRISBEE 
BACKGAMMON 
FREEZE TAG 

When the left argument has a rank greater than one, each axis represents 
a level of comparison and the last axis receives the highest priority. For 
example, when the left argument has two rows, each containing an alphabet 
in a different font, APL gives higher priority to the order specified by the 
columns (last axis) than it gives to the fonts specified by the rows (first axis). 
For this reason, the word HELM precedes the word HEEL in the end result of 
the following example: 
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ALPHA 5+ ' ABCDEFGHI JKLMNOPQRSTUVWXYZ 
ABCDEFGHI JKLMNOPQRSTUVWXYZ ' 

WORDS+QBOX 'HOPE 
NASAL 
HEEL 
HELM 
HEEL 
NEST 
NEAR 
PALM' 

X*- *■ ALPHA51 WORDS 
72358614 

WORDS IX ;] 
NEAR 
NASAL 
HEEL 
HEEL 
PALM 
NEST 
HOPE 
HELM 

Duplicate items, such as character blanks, in the left argument (A ) may yield 
an unexpected collating sequence. APL compares the locations of a duplicate 
item and bases its position in the final collating sequence on this comparison. 
The final location of a duplicate item is the minimum value along each axis 
for each occurrence. For example, if a duplicate w appears at locations 113 
and 2 1 2 in a three-dimensional array, then the position of the W in the final 
collating sequence is 1 1 2. If the position 1 1 2 is occupied by a value other 
than W, the two are treated as equivalents: 

Q+D+2 2 3p'ABCDEFGCIJKL' 
ABC 
DEF 

GCI 
JKL 

D^B+4 3p' ABFAAFACFABF' 
ABF 
AAF 
ACF 
ABF 

B[2)fB;] uNOTE THAT C AND B ARE EQUIVALENT 

ABF 
ACF 
ABF 
AAF 
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In the following example, D appears at locations 1 2 and 2 1, and B appears 
at locations 1 1 and 2 2. In the final collating sequence, both are positioned at 
location 1 1 and are treated as equivalent values: 

0<-L<-2 2p <BDDB< 
BD 
DB 

Q<-J?<-5 2p 'DBBDBDDBBD' 
DB 
BD 
BD 
DB 
BD 

L^R flC AND B ARE EQUIVALENT, NO CHANGE 

12 3 4 5 

For more information about how the dyadic grade function is implemented, see 
Smith, H.J., "Sorting - A New/Old Problem." APL Quote Quad 9 (June 1979) 
ppl23-127. 

Possible Errors Generated 



10 LENGTH ERROR (ARGUMENT STRING IS TOO LONG) 

15 DOMAIN ERROR {ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

30 AXIS DOMAIN ERROR (INCORRECT OPERATION) 
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4 Monadic Grade Up 
Form 

kB ILK1B 

4 is formed with A and | 

Argument Domain 

Type Homogeneous 

Shape Matrix, vector, or scalar (not singletons of rank > 2 ) 

Depth or l (simple) 

Result Domain 

Type Nonnegative integer 

Rank l 

Shape (<t>pB) LK1 

Depth l (simple) 

Implicit Arguments 

010 UB when Q 10 ■*- l is identical to l + 4lB when QIO +■ o) 



Description 



The monadic i function returns a numeric vector whose items can be used to 
sort the items of the argument in ascending order. Thus, grade up does not 
actually sort arrays; it creates a permutation vector of the index numbers of 
the argument array's items, and this vector can then be used to sort the array. 

Sorting a vector requires two steps. First, the vector is the argument to the 
grade up function, and then the result is used to index the vector: 

A+2 9 7 4 3 10 i+ 

15 4 7 3 2 6 
ALB1 

2 3 t 4 7 9 10 
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If two or more items of a vector or matrix have the same value, the order of the 
items is determined by the relative positions of the items in the original array 
(this is called a stable sort). For character arguments, the collating sequence is 
determined by the value of DAV. Note that for numeric arguments, the result is 
not D CT-dependent. 

When you use the grade up function to sort a matrix, APL treats each row 
or column as a string. Thus, you can use the function to sort row by row or 
column by column, but not to sort individual items within a row or column. 
When applied to a matrix, the result of the grade up function is a vector whose 
length is equal to the number of rows or columns in the matrix. 

The following sorts the matrix B by rows and then by columns: 

B<-3 5p3 2 1 5 3 1 9 7 3 2 8 
*B 
2 3 1 

2 3 1 

BUB;] 

3 19 7 
3 2 8 
3 2 15 

*[1]B 
5 3 2 14 

B[:4[1]B] 
12 3 5 
9 13 7 
2 3 8 

In this example, the original second row becomes the first row, the third row 
becomes the second row, and the first row becomes the third row. Note that A B 
and 4 [ 2 ] B are equivalent. You can also sort character arrays by rows or by 
columns. For example: 

D<-B<-3 5o<ALLENALLINALLAN< 
ALLEN 
ALLIN 
ALLAH 

BtkB;] 
ALLAH 
ALLEN 
ALLIN 

B[;K1]B] 
AELLN 
AILLN 
AALLN 
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If the argument to i is a scalar, the ravel function is applied to extend it to a 
one-item vector, and the result of the j function is , □ 10: 

R 
1 

ppR 

1 

Note that CT is not an implicit argument to the grade up function. 

Possible Errors Generated 



9 RANK ERROR {NOT A SCALAR, VECTOR, OR MATRIX) 
15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 
2 7 LIMIT ERROR (INTEGER TOO LARGE) 
28 AXIS RANK ERROR (NOT VECTOR DOMAIN) 

2 9 AXIS LENGTH ERROR (NOT SINGLETON) 

3 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 
3 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 

3 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

3 AXIS DOMAIN ERROR (INCORRECT TYPE) 

3 AXIS DOMAIN ERROR (NOT AN INTEGER) 

3 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) 
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A Dyadic Grade Up 
Form 

A^B 

4 is formed with & and | 

Left Argument Domain 



Type 


Character 


Shape 


Any 


Depth 


or l (simple) 


irgumenl 


: Domain 


Type 


Character 


Shape 


Any 


Depth 


o or l (simple) 


Domain 




Type 


Nonnegative integer 


Rank 


l 


Shape 


1+ p T B 


Depth 


l (simple) 



Implicit Arguments 

QIO GUB when QIO *■ l is identical to 1 + Ak-B when 010 *■ o) 

Description 

The dyadic k function returns a numeric vector whose items can be used to 
sort the items along the first axis of the right argument in ascending order. 
(The sort is performed according to the collating sequence defined in A .) Grade 
up does not actually sort arrays; it creates a permutation vector of the index 
numbers of the argument array's items, and this vector can then be used to 
sort the array. If either argument is empty, the result of the grade function is 
i l + p B. If the length of the first axis of B is one, then the result is ,010. 
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If two or more items of the right argument have the same value, the order of 
the items is determined by their relative positions in the original array (this is 
known as a stable sort). 

Sorting an array is accomplished in two steps. First, the array is the right 
argument to the grade function, and then the result is used to index the array. 
The left argument determines the order in which APL collates the items of the 
right argument. For example: 

ALPHA1+' IVXLCDM' 
N+'CMXIVCILI' 
X <- D - (ULPHAl)iN 
2 16 8 3 5 4 7 9 

nxi 

MCCLXVIII 

DATES+VBOX 'MCCLXVIII 
VIII 
MLXXIII 
DCCCXXIII 
CLXVI 
MDCLIII 
CLXXI 
XVII I < 

X +■ D +■ ALPHAlbDATES 
2 8 5 7 4 3 16 

DATESlX-,1 
VIII 
XVIII 
CLXVI 
CLXXI 
DCCCXXIII 
MLXXIII 
MCCLXVIII 
MDCLIII 

HEX*-' 0123H567 8$ ABCDEF' 

HD+VBOX <8E7 
ZDA 
976 
AE8 
F8 
3D5 
W 
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X *• D *- HEXkBD 
7 5 6 2 13 4 
HDLX-J 

10 

F8 
3D5 
3DX 
8E7 
976 
AE8 

To sort an array that contains more than one font, you can use sequences 
similar to the following, depending on the desired result: 

ALPBA2+U+ , AABBCCDDEEFFGGBBIIJJKKLLMMNB00PPQ. 
ZQRRSSTTUUVVUWXXYYZZ < 
AABBCCDDEEFFGGBBIIJJKKLLMMNNOOPPQ. 
ZQRRSSTTUUVVWWXXYYZZ 

UORDS+QBOX 'BOPE 
NASAL 

BEEL 
BELM 
BEEL 
BEST 
BEAR 
PALM' 

X <- U +■ ALPBA2 WORDS 
11536278 

WORDSIX-J 
BELM 
BOPE 
BEEL 
BEEL 
BEST 
BASAL 

BEAR 
PALM 

ALPBA 3-M> ' ABCDEFGBIJKLMBOPQRSTUVWXYZABCDEIGBIJKL 
MHQPQRSTUVWXYZ' 

ABCDEFGHIJKLMNOPQRSTUVNXYZABCDEIGBIJKL 
MNOP£RSTUYWXYZ 

X *■ D <- ALPBAZkUORDS 
41685327 
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i Dyadic Grade Up 



WORDS iX;l 



HELM 

HOPE 

NEST 

PALM 

HEEL 

HEEL 

NASAL 

NEAR 

If any items appear in the right argument when they have not been specified 
in the left argument, APL considers them equal and places them at the end of 
the sort sequence. For example: 

ALPHAS' ABCDEFGHIJKLMNOPQRSTUVUXYZ' 

GAMES+-UBOX 'FREEZE TAG 
MONOPOLY 
CHESS 

HIDE AND SEEK 
BACKGAMMON 
FRISBEE' 

X + □ <- ALPHAH^GAMES 
5 16 4 2 3 

GAMES IX ;1 
BACKGAMMON 
FREEZE TAG 
FRISBEE 
HIDE AND SEEK 
MONOPOLY 
CHESS 

When the left argument has a rank greater than one, each axis represents 
a level of comparison and the last axis receives the highest priority. For 
example, when the left argument has two rows, each containing an alphabet 
in a different font, APL gives higher priority to the order specified by the 
columns (last axis) than it gives to the fonts specified by the rows (first axis). 
For this reason, the word HEEL precedes the word HELM in the end result of 
the following example: 
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| Dyadic Grade Up 



ALPHA5+2 26p ' ABCDEFGHIJKLMNOPQRSTUVWXYZ 
ABCDEFGEIJKLMKQPQRSTmXU ' 

MRDS+QBOX 'HOPE 
NASAL 
KEEL 
HELM 
HEEL 
NEST 
NEAR 
PALM' 

X *■ U *■ ALPHAS WORDS 
53412768 

WORDS IX;] 
HEEL 
KEEL 
HELM 
HOPE 
NASAL 
NEAR 
NEST 
PALM 

Duplicate items, such as character blanks, in the left argument (A ) may yield 
an unexpected collating sequence. APL compares the locations of a duplicate 
item and bases its position in the final collating sequence on this comparison. 
The final location of a duplicate item is the minimum value along each axis for 
each occurrence. For example, if a duplicate W appears at locations 113 and 
2 1 2 in a 3-dimensional array, then the position of the W in the final collating 
sequence is 1 1 2. If the position 1 1 2 is occupied by a value other than W, the 
two are treated as equivalents. 

U+D+2 2 3p 'ABCDEFGCIJKL' 
ABC 
DEF 

GCI 
JKL 

U+B+H 3p' ABFAAFACFABF' 
ABF 
AAF 
ACF 
ABF 

BIDkB;] nNOTE THAT C AND B ARE EQUIVALENT 

AAF 
ABF 
ACF 
ABF 
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4 Dyadic Grade Up 

In the following example, D appears at locations 1 2 and 2 1, and B appears 
at locations 1 1 and 2 2. In the final collating sequence, both are positioned at 
location 1 1 and are treated as equivalent values. 





D+Lf-2 2p 'BDDB' 


BD 




DB 




DB 


D<-J?*-5 2p' DBBDBDDBBD' 


BD 
BD 




Ub 

BD 






LkR 


1 2 


3 4 5 



flfl AND B ARE EQUIVALENT, NO CHANGE 

For more information about how the dyadic grade function is implemented, see 
Smith, H.J., "Sorting - A New/Old Problem," APL Quote Quad 9 (June 1979) 
pp 123-127. 

Possible Errors Generated 

10 LENGTH ERROR {ARGUMENT STRING IS TOO LONG) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

3 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

30 AXIS DOMAIN ERROR (INCORRECT OPERATION) 
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i Index Generator 
Form 

i 

Argument Domain 



Type 


Nonnegative near-integer 


Shape 


Singleton 


Depth 


o or l (simple) 


Domain 

Type 


Nonnegative integer 


Rank 


l 


Shape 


,B 


Depth 


l (simple) 



Implicit Arguments 

QIO (i when QIO «- 1 is identical to 1 + i when QIO *■ 0) 

Description 

For an argument B , the monadic i function generates a vector of consecutive, 
ascending integers starting with the value of the index origin. For example: 

1 2 3 4 

PA 
4 

2*i 12 aPOHERS OF 2 

2 1 8 16 32 64 128 256 512 1021 2048 4096 

2 5pil0 
12 3 4 5 
7 8 9 10 

X<-7 1 3 4 

ipX 
12 3 4 
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i Index Generator 

If the index origin is i , the integers have values l through B ; if the index 
origin is o , the integers have values o through B - 1: 

010 

1 

i5 
12 315 

QI0+-O 

i5 
0123i( 

Regardless of the value of □ 10, i o is the numeric empty vector: 

i0 

(APL outputs a blank line) 
piO 


Possible Errors Generated 

9 RANK ERROR {NOT VECTOR DOMAIN) 

10 LENGTH ERROR (NOT SINGLETON) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NEGATIVE NUMBER NOT ALLOWED) 

15 DOMAIN ERROR (NOT AN INTEGER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 



1-106 APL Reference Manual 



Primitive Mixed Functions 

i Index Of 



i Index Of 
Form 

Ax B 

Left Argument Domain 



Type 


Any 


Shape 


Vector domain 


Depth 


Any 


Right Argument 


Domain 


Type 


Any 


Shape 


Any 


Depth 


Any 


Result Domain 




Type 


Nonnegative integer 


Rank 


ppfl 


Shape 


PS 


Depth 


or l (simple) 



Implicit Arguments 



□ CT (determines comparison precision) 

□ 10 (A\B when □ 10 «- l is identical to l + AxB when D 10 *- o ) 



Description 



The dyadic i function returns the position of the first occurrence in the left 
argument of the corresponding items in the right argument. For example: 



4 9 6 8 i 6 H 

3 1 



The result indicates that 6 is the third item in the left argument and 4 is the 
first item. 
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i Index Of 

The result will always have the same shape as the right argument, so that an 
index is returned for each of the values in the right argument. If a particular 
value in the right argument does not appear in the left argument, APL 
supplies a value equal to the last index value of the left argument plus one. 
For example: 

'ABCDEFGH'i' HEADER' 

8 5 1^59 

The value R does not appear in the left argument, so APL returns the value 9 
(there are eight values in the left argument) for the position corresponding to 

R. 

Note that the dyadic i function is Q 10 -dependent: when D 10 is , each item 
in the result is one less than when □ 10 is l : 

UIO-i-0 

'ABCDEFGH'x' HEADER' 
7 4 3 4 8 

If the right argument of the dyadic i function is empty, the result is empty. If 
the left argument is empty, the result is all Is (0 IO-*-+ 1): 

(i0)i2 5pil0 
11111 
11111 

Note that comparisons of the items in the right and left arguments are defined 
in terms of the match (= ) function (and so are D CT-dependent). Because match 
allows mixed-type arguments, you can compare characters with numbers. 
However, such a comparison is always false, so that if you use mixed-type 
arguments for dyadic i , the items in the result will be equal to the last index 
value of the left argument plus one. 

Further examples: 

n+VIC+'ABC 
+---+ 
\ABC\ 
+ — + 

U+V00F+ 'AB' "3 'ABC 99 1 

+--+ 3 + + 99 1 

\AB\ \ABC\ 
+ --+ + + 
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VOOF i VIC 
t 2 

aNOTE THAT DYADIC i IS UIO-DEPENDENT 

DIO-i-0 

VOOF i VIC 
3 1 

Q+-II?*- p (1 2 3) 'ABC 

(APL outputs a blank line) 

□«-V<-(l 2 3) '4BC 

+ + + + 

|1 2 3| UBC| 
+ + + + 

V i XIP aEMPTY RIGHT ARGUMENT 

(APL outputs a blank line) 

p V i XIP 


XIP i V nEMPTY LEFT ARGUMENT 



Possible Errors Generated 



9 RANK ERROR (NOT VECTOR DOMAIN) 
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n Intersection 
Form 

AnB 

Left Argument Domain 



Type 


Any 


Shape 


Any 


Depth 


Any 


Right Argument 


Domain 


Type 


Any 


Shape 


Any 


Depth 


Any 


Result Domain 




Type 


See explanation below 


Rank 


1 


Shape 


pu ( ( ,A) eB) / ,A 


Depth 


- 



Implicit Arguments 

D CT (Determines comparison precision) 

Description 

The dyadic n function returns the common items found in both arguments. 
The result is the intersection of the arguments with the duplicate items 
removed. Note that the order of the items in the result is not predictable. For 
example: 
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<CBEFGH< n 2 3p ' ABCD' 
CB 

(2 3p <ABCD<) n 'CBEFGH' 
BC 

(16) n 5 7 3 i* 
3 4 5 

5 7 3 4 (1 1 6 

3 4 5 

You can use the intersection function to remove duplicate items from an 
argument. However, the unique function is the preferred method for this task. 
For example: 

A<rl 212 345 1 65 34 67 1 34 ^DUPLICATES ARE 1 AND 34 
A n A 

1 212 345 65 34 67 

u A 

1 212 345 65 34 67 

The type of the result depends on the types of the arguments, as shown in the 
following table: 



Argument Resulting Type 



Neither empty Same as left argument 

One empty Same as nonempty argument 

Both empty Same as left argument 



The n function compares items in terms of the match (= ) function, which uses 
the value of OCT. Since match allows mixed-type arguments, you can compare 
characters with numbers. However, such a comparison is always false, so that 
if you use mixed-type arguments for dyadic n , the result will be empty. 

Note that the following definition applies: AnB *-->■ u ( { ,A) =B) / ,A, where 
the order of the items may differ. 

Further examples: 

CM<-c , 3 

+-+ 

|3| 
+ - + 

D<-B<-(1 2 5) 
1 2 5 
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D<-ra2>(c,_3) (12 5) 1 
+ + + + 1 

I+-+I |1 2 5| 
I 1311 + + 

+ + 

R+MIC+2 2 p A B ~i 

+ — t + + 

I+-+I |1 2 5| 

II3II + + 

I+-+I 

+ + 

~1 

MIC n WRL_ aZERO NOT IN INTERSECT 

+ — + + + ~1 

I+-+I U 2 5| 

I|3|| + + 

I+-+I 
+ + 

MIC u c,3_ »N0 INTERSECTION BETWEEN TWO ARGUMENTS 

+ — + + + 1 +-+ 

I+-+I 11 2 5| | 3 1 

||3|| + + +- + 

I+-+I 
+ + 

n+VANHl 2 3) 'ABC (c,i 2 3) nCREATE VAX 

+ + + + + + 

|1 2 3| \ABC\ |+ +| 

+ + +---+ ||1 2 3 | | 

|+ +| 

+ + 

At-{1 2 3) 'A' aCREATE NEW A 

A n VAN 

+ + 

U 2 3| 
+ + 



Possible Errors Generated 

None. 
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= Match 




Form 




A=B 




= is formed with = and _ 


Left Argument Domain 


Type 


Any 


Shape 


Any 


Depth 


Any 


Right Argument 


Domain 


T^e 


Any 


Shape 


Any 


Depth 


Any 


Result Domain 




Type 


Boolean 


Rank 





Shape 


i o (scalar) 


Depth 


(simple scalar) 



Implicit Arguments 

D CT (determines comparison precision) 

Description 

The dyadic = function determines whether the two arguments are identical in 
rank, shape, and value. The result is a Boolean scalar: true, if the arguments 
are identical, and false if they are not. For example: 
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= Match 






'ABCD' = 'ABCD' 


1 






>ABCD< = 'ACBD' 









'ABCD' = 2 2p ' ABCD 









'A' = , 'A' 









12 3=123 


1 






12 3 = 12 









123 = 1223 









1 2 3 = '1 2 3' 









" = lO 








The = function compares the simple items in terms of the equal (=) function 
and identifies equal items based on the value of D CT. For example: 

UCT 
IF 15 

H = 4-5iTl6 

1 

Further examples: 

U+A+H 

+-+ 
+-+ 



4 = B nJVOW DIFFERENCE BETWEEN = MD 

4 = fl 





+-+ 

HI 
+-+ 

□+7ICM1 2 3) (c,4) 

+ + + + 

|1 2 3| |+-+| 

+ + | KM 

+ — + 
+-+ 

hi 

+-+ 
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Q+-REDH1 2 3) J 
1 2 3 +-+ 

I'M 

+-+ 

RED = VIC 


D-HHc(l 2 3) 

+ + 

|1 2 3| 
+ + 

Possible Errors Generated 

None. 



Primitive Mixed Functions 

= Match 
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fB Matrix Divide 




Form 




AEB 

i is formed with Q and^ 


Left Argument Domain 


TVpe 

Shape 

Depth 


Numeric 

Matrix, vector, or scalar (not singletons of rank < 2 ) 

or l (simple) 


Right Argument Domain 


Type 

Shape 

Depth 


Numeric 

Matrix, vector, or scalar (not singletons of rank < 2 ) 

or l (simple) 


Result Domain 




Type 
Rank 
Shape 
Depth 


Numeric 

T~2+ ( ppA) tppfl 
( 1+ pB) , l+p4 
or l (simple) 



Implicit Arguments 

D CT (used in the test for singularity) 

Description 

For arguments A and B , the dyadic i function determines the generalized 
solution R to the linear system A = B+ . * R. If B has more rows than columns, 
then dyadic i returns the least-squares solution to the linear system. 

The matrix divide function treats scalars and vectors as one-column matrices 
(except when it is determining the shape of the result). 



1-116 APL Reference Manual 



Primitive Mixed Functions 

ES Matrix Divide 

The following example shows the use of the matrix division function in solving 
the linear equations 3A+B=9 and 2A-B=1: 

JT-t-9 1 

y«-2 2p3 1 2 1 

xm 

2 3 

In the expression H Y, Y is a matrix whose values are the coefficients of the 
equations, and X is a vector containing the constant terms 9 and 1. 

The result is a vector in which the first item is the value of A in the linear 
equations, and the second is the value of B . The following example shows other 
uses of matrix divide, including a least-squares solution: 





Q*AH,\.l- 


5] 2 5) 


2 1 






5 1 


B<-10 19 
pU<-X*-BM 




3 4 






2 


A+.*X 




10 19 








LM+(,[1. 


.5]i5), 


1 1 






2 1 






3 1 






4 1 






5 1 







DPP 

10 

B<-2.001 2.998 4.002 4.997 6.01 

U+X+BEA 
1.0017 0.9965 

B-_A+.xX 
0.0028 0.0019 0.0004 0.0063 0.005 

0.2 "0.1 9. 3564026312 19 0.1 _0 . 2 

0.8 0.5 2.000000000£~1 "0.1 0.4 
X+.*A 
1.000000000EO 1.040834086E 17 
2.775557562E"17 1. 00O0OO00OE0 

For more information about how the matrix divide function is implemented, 
see Jenkins, M. A., The Solution of Linear Systems of Equations and Linear 
Least Squares Problems in APL. New York: IBM Scientific Center, Technical 
Report No. pp320-2989, June 1970; and Businger, Peter, and Golub, Gene H. 
"Linear Least Squares Solutions by Householder Transformations." Numerische 
Mathematik 7 (1965) pp269-276. 
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Possible Errors Generated 

9 RANK ERROR (NOT A SCALAR, VECTOR, OR MATRIX) 

10 LENGTH ERROR (FEWER ROWS THAN COLUMNS) 
10 LENGTH ERROR (NUMBER OF ROWS MUST MATCH) 
15 DOMAIN ERROR (DIVISION BY ZERO) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (SINGULAR MATRIX) 

27 LIMIT ERROR (FLOATING OVERFLOW) 
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EB Matrix Inverse 
Form 



is 

@ is formed with D and * 



Argument Domain 



Type Numeric 

Shape Matrix, vector, or scalar (not singletons of rank < 2 ) 

Depth o or l (simple) 



Result Domain 



Type 


Numeric 


Rank 


PPS 


Shape 


<t>pB 


Depth 


o or l (simple) 



Implicit Arguments 

D CT (used in the test for singularity) 

Description 

The monadic i function inverts a matrix to facilitate matrix division and a 
variety of other matrix operations. 

If the argument is a matrix, its rows must be linearly independent. 

If the argument is a scalar or vector, the result is a scalar or vector, 
respectively, but the result's items are obtained by treating the argument 
as a one-column matrix. Formally expressed, for an argument B : 

m +-({ 1,1) pi, (I+- I +pS)pO)@ (2 + (pB) , ll))pfl 

Note that the matrix product of B and @fl is the identity array. Formally 
expressed, for an argument B : 
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H) Matrix Inverse 

For example: 

U+A-<-i( i3)«.+"l+i3 

1 0.5 0.3333333333 

0.5 0.3333333333 0.25 

0.3333333333 0.25 0.2 

Jl+X+ftA 
9 36 30 
"36 192 "180 
30 "180 180 
X+.*A 
_1. 00000000020 2.220446049£ 16 1 .665334537E 16 
~4.440892099£~15 1.000000000SO "1. 332267630E"15 
4.440892099£~15 2.2204460W15 1.00000000050 

For more information about how the matrix inverse function is implemented, 
see Jenkins, M. A., The Solution of Linear Systems of Equations and Linear 
Least Squares Problems in APL. New York: IBM Scientific Center, Technical 
Report No. pp320-2989, June 1970; and Businger, Peter and Golub, Gene H. 
"Linear Least Squares Solutions by Householder Transformations." Numerische 
Mathematik 7 (1965) pp269-276. 

Possible Errors Generated 



9 RANK ERROR (NOT A SCALAR, VECTOR, OR MATRIX) 

10 LENGTH ERROR ( THERE ARE FEWER ROWS THAN COLUMNS) 
15 DOMAIN ERROR (.DIVISION BY ZERO) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (SINGULAR MATRIX) 

27 LIMIT ERROR (FLOATING OVERFLOW) 
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e Membership 
Form 

AeB 

Left Argument Domain 



type 


Any 


Shape 


Any 


Depth 


Any 


Right Argument 


Domain 


"type 


Any 


Shape 


Any 


Depth 


Any 


Result Domain 




Type 


Boolean 


Rank 


ppA 


Shape 


pA 


Depth 


o or l (simple^ 



Implicit Arguments 

□ CT (determines comparison precision) 

Description 

The dyadic e function determines whether particular items of the left 
argument array occur as items of the right argument array. The result is 
a Boolean array whose shape is the same as that of the left argument: a l 
indicates that the corresponding item in the left array is present somewhere in 
the right array; a indicates that the item is not present. For example: 

A*-2 3p7 8 2 t 6 9 

1 

1 1 
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The result identifies the items in A that are also items in i 6 . 

You can use the compression function (/ ) in conjunction with the membership 
function (e ) to identify the particular items that are members of both 
argument arrays: 

U*-A*- ' ABCDEFGR < e ' HEADED ' 
10 110 1 

A/'ABCDEFGH' 
ADEH 

Note that comparisons of the items in the right and left arguments are denned 
in terms of the match (= ) function (and so are D CT-dependent). Since match 
allows mixed-type arguments, you can compare characters with numbers. 
However, such a comparison is always false, so that if you use mixed-type 
arguments for dyadic e , the result will be all s. 

Further examples: 

Q*-ACT<-(1 2 3) 'ABC {c,H) 

+ -+ + + + + 

|1 2 3| \ABC\ |+-+| 

+ + +-~+ I Ul I 

|+-+| 

+ + 

Q+-B0Y<-2 2 p (c,4) <BC (1 2 3) 
+ — + +--+ 
I+-+I \BC\ 

I hi I +-- + 

I+-+I 

+ + 

+ + 

U 2 3| 
+ + 

BOY e ACT 
1 
1 

ACT e BOI 
10 1 

Possible Errors Generated 

None. 
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=> Pick 
Form 

A^B 

Left Argument Domain 



Type 


Nonnegative near-integer 


Shape 


Vector domain 


Depth 


Less than or equal to 2 


irgumer 


it Domain 


Type 


Any 


Shape 


Any 


Depth 


Any 



Result Domain 



Type 


Any 




Rank 


Any 




Shape 


Any 




Depth 


(=B)- 


- p A (provided A is along the deepest path) 



implicit Arguments 

UIO (A=B when D J0+-1 is identical to ( l + A) ^B when QIO^o) 

Description 

The dyadic => function selects and discloses an item from an existing array. 
The items in A specify the coordinates of items in B . For example: 

7«-21 22 23 24 25 26 

2dF aSELECT SECOND ITEM IN V 

22 

K[2] nNOTE SIMILARITY TO INDEXING 

22 
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3 Pick 

You can select an item from any depth in an enclosed array. The length of A 
determines the depth of the selected item: when A has one item, the selection 
is from the top level of B ; when A has two items, the selection is from the 
second level; and so on. For example: 

U*-BH'1A< 'IB') ('2A' '2B') ('3A' ' 3B ' ) 

+ + + + +--■ + 

I+--+ +--+| |+--+ +--+| |+--+ + --+| 
||14| llflll \\2A\ \2B\\ \\3A\ |3B|| 
I+--+ +--+| |+--+ +--+| |+--+ +--+| 
+ + +- + + + 



nLEFT ARG LENGTH IS 1, PICK FROM TOP LEVEL 
Q-<-Z<-23B 

|2Jl| \2B\ 
+ -- + +--+ 

= Z 
2 

PZ 
2 

D+vM 2^B fiPICK FROM SECOND LEVEL 

IB 

=1 
1 

PX 
2 

The length of each item of A is equal to the rank of the corresponding array 
in B . The first item in A has a length equal to the rank of B ; the second item 
has a length equal to the rank of the array selected by the first item in A ; the 
third item has a length equal to the rank of the array selected by the second 
item in A ; and so on. In the following example, the rank of H is 2 , and the 
rank of item H [ l ; 2 ] is 3 . To select an item from H [ 1 ; 2 ] , the first item of A 
must contain two elements, and the second item must contain three elements. 
When you pick from the top level of an array, A must have length l , and if A 
is enclosed, the contents must be in the simple vector domain. 
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Q*#<-2 2 p (10m5) (2 3 4pi24) (2 2pl00xi4) 1000 
+ + + + 

|10 20 30 i+0 50 1 | 1 2 3 4| 
+ + | 5 6 7 8| 

| 9 10 11 12 | 

I I 

1 13 14 15 16 | 
i 17 18 19 20| 
| 21 22 23 24 1 

+ + 

+ + 1000 

I 100 200 | 
I 300 400| 

+ + 

sR 
2 

D<-Z<-((1 2) (2 2 3) 
19 

= Z 


(cl 2)?H 
12 3 4 
5 6 7 8 
9 10 11 12 



H nPICK FROM SECOND LEVEL 



13 14 15 16 

17 18 19 20 

21 22 23 24 

1 2^H 

10 LENGTH ERROR (LEFT ITEM LENGTH NOT EQUAL TO SELECTED ITEM RANK) 

1 2 = fl 



When B and all the items in B are in the vector domain, then A is in the 
simple vector domain. When A is empty, then A=>B -*--»- B. 

U+F+'A' 'AN' ('ANT' (' ANTI' 'ANTIC')) 
A + -- + + + 



\AN\ 

+-- + 



+ + t +| 

|Mr| |+ — + + +| j 

+---+ | \ANTI\ \ANTIC\ | | 

l+ — - + + +11 

+ +| 

+ + 

F 



pF 
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=> Pick 

p" F fiSHAPE OF EACH OF F 

++ +-+ +-+ 

II |2| |2| 

++ +-+ +-+ 

Q+-P+-3 3 F aPICK 3RD ITEM OF F 

+ + + + 

\ANT\ |+ + + +| 

+— + | \ANTI\ \ANTIC\ I 

I+-— + + +1 

+ + 

=P 
3 

pP 
2 

Q^3 2 3 F nPICK 1 LEVEL DEEPER 

+ + + + 

\ANTI] \ ANTIC] 
+ + + 1 

2 

pe 

2 

Q-<-i?-<-3 2 1 ^ F HPJCiC ANOTHER LEVEL DEEPER 

ANTI 

=J? 
1 

pi? 
it 

D-<-5^3 2 1 3 3 F a PICK F#CM 1H £FKFL OF F 

r 



P5 

(APL outputs a blank line) 

O(i0)3F 

G^F 
1 

When an item in B is a scalar, the corresponding item in A must be empty. For 
example: 
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OJM 2p< ABC (c2 2p(l 2)(2 3)(3 4 ) ( 4 5) 

+ + + + 

\ABC\ |+ + 

+ + I 1+ + + — +1 

111 2| |2 3|| 

|t — + + — +| 

|+— + + — +| 

113 4| |4 5|| 

|+— + + — +| 

+ +| 

+ + 

+ + + + 

\XYZ\ |12 3 4 5| 

+ + + + 

=X 

4 

px 

2 2 

p" X 
+ -+ ++ 
I 3 | II 

+ -+ + + 
+ -+ +- + 
I 3 | |5| 

+ -+ +- + 

(c 1 2)=Z 
+ + 

|+ + + +| 

111 2| |2 3|| 

|+ + + +| 

|+ + + +| 

113 4| |4 5|| 

|+ + + +| 

+ + 

(1 2 ) " =>Jf 

+ + + + 

U 2| |2 3| 

+ + + + 

+ + + + 

|3 4| |4 5| 
+ + + + 

(12) " (2 1)dZ 

3 4 



Primitive Mixed Functions 

=> Pick 

<XYZ< (i5) 



rPICK I[l;2] 



aUSE EMPTY TO PICK INTO SCALAR 



iPJCif DEEPER 



To select more than one item from an array, use pick with the each (" ) 
operator. For example: 
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=> Pick 

D<-y<-2 3pc[2]Xt-6 2p ," 'ABCDEFGNIJKL' 
+ + + + + + 

|+-+ +-+| |+-+ +-+| |+-+ +-+| 

IMI IBM lid \D\\ \\S\ \F\\ 

|+-+ +-+| |+-+ +-+| |+-+ +-+| 

+ + + + + + 

+ + + + + + 

|+-+ +-+| |+-+ +-+| j +-+ +-+| 

iiffi urn mi mi mi mi 
i+-+ +-+i i+-+ +-+i i+-+ +-+i 
+ + + + + + 

GETA+(1 1) 1 

GETL+{2 3) 2 

GETA 3 7 
A 

GETL = 7 
L 

GETA GETL =>" cY nUSE EACH TO PICK MULTIPLE ITEMS 
+-+ +-+ 
\A\ |I| 
+-+ +-+ 

GETA GETL =" J J rTHIS IS AN ALTERNATIVE FORM 
+-+ +-+ 

Ml |L| 
+-+ +-+ 

The following relationship between the take (+ ) function and pick is true for 
any nonempty B: + B *■-*■ (c(ppB)pQ 10 ) => B. 

Possible Errors Generated 

9 RANK ERROR (LEFT ITEM NOT VECTOR DOMAIN) 

9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (LEFT ARGUMENT LENGTH GREATER THAN RIGHT ARGUMENT 
DEPTH) 

10 LENGTH ERROR (LEFT ITEM LENGTH NOT EQUAL TO SELECTED ITEM RANK) 

li+ DEPTH ERROR (LEFT ARGUMENT DEPTH GREATER THAN 2 ) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (INDEX LESS THAN INDEX ORIGIN) 

15 DOMAIN ERROR (INDEX OUT OF RANGE) 

1-128 APL Reference Manual 



Primitive Mixed Functions 

=> Pick 



15 DOMAIN ERROR {NOT AN INTEGER) 
2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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, Ravel 



, Ravel 
Form 

,B ,iK2B 

Argument Domain 

Type Any 

Shape Any 

Depth Any 



Result Domain 




Type 


Same as argument 


Rank 


l (for ,B) 


Shape 


x 1 p B (for , B) 


Depth 


ir^s 


Implicit Arguments 




None. 




■ 





The monadic APL, function returns a vector made up of the items of the 
argument array, stored in row-major order (by increasing index position). For 
example: 

k*-l 3pl 2 3 ^ 5 6 
Q+B+.A 
1 2 3 H 5 6 
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, Ravel 



U+A+2 3 3 pi 18 
1 2 3 
4 5 6 
7 8 9 

10 11 12 

13 14 15 

16 17 18 
,A 
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 



18 
2 3 3 



PA 



If the argument array is a scalar, APL returns a vector that contains one item. 
Note the difference in the shape of a scalar and the shape of a scalar to which 
the ravel function has been applied: 

P 1 * 

(APL outputs a blank line) 

1 

If the argument is a vector, APL returns a vector that is identical to the 
argument: 

Ai-i6 

A 
12 3 4 5 6 

,A 
12 3 4 5 6 

If the argument is an empty array of any rank or shape, APL returns an empty 
vector that is the same type as the argument. 

When you use ravel with an axis argument, K is in the vector domain and its 
items are numeric. The result depends on whether K is a noninteger singleton 
or a near-integer vector. (If K is a near-integer singleton, the shape of B is 
unchanged.) 

When the axis argument is a noninteger singleton, APL inserts a new axis (of 
length one) in the indicated position. For example, if AT is a fraction between 
1 and 2, APL will insert an axis between the first and second axes of B . Note 
that K must be between ~ l+Q 10 and □ 10+ p p B. The rank of the result is 

ltppB: 
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, Ravel 

4^2 3p9 8 7 6 5 1 
,[1.5]4 
9 8 7 

6 5 4 

P,[1.5]il 
2 13 

If you specify a noninteger singleton axis when B is a scalar, the result is a 
one-item vector: 

,[.5] 28 
28 

P,[.5] 28 
1 

When the axis argument is a near-integer vector, APL merges the specified 
axes into a single axis. In this case, K must contain contiguous ascending axis 
numbers between Q 10 and ppS. The rank of the result is 1+ ( p p B ) - p , K . If K 
is empty, then the result is ( ( p B ) ,l)pB. Note that , [ i p p B] B is the same 
as ,B: 

B+2 3 6p' SARAH SELLS SHELLSBETH BUYS BOATS ' 

B 
SARAH 
SELLS 
SHELLS 

BETH 
BUYS 
BOATS 

PB 
2 3 6 

,[2 3]B 
SARAH SELLS SHELLS 
BETH BUYS BOATS 

P,[2 3]B 
2 18 

If you want to add an axis to the end of the shape of an array, you can use i 
as the axis argument. If you want to add an axis to the beginning of the shape 
of an array, you can use ~ . 5+010 as the axis argument: 

4<-2 3p 9 7 6 5 4 
,LiOlA 
9 

7 
6 
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, Ravel 

5 

9 

P,[iO]il 
2 3 1 

,[".5 + 0IO]A 
9 7 6 
5 4 9 

p,[".5 + 010] A 
12 3 

If you specify D 10 or i o as the axis argument when B is a scalar, the result is 
a one-item vector: 

,[1] 28 
28 

P,[l] 28 
1 

,[i0] 6 
6 

P,[iO] 6 
1 

Further examples: 

Ui-Af-c . 3 
Q+B<-<ABC' 



0.3 

ABC 



0+D<-~2 
'2 

B+Ei-2 2 p A B C D 
0.3 +---+ 
\ABC\ 
+ — + 
++ "2 

II 
++ 

P E 
2 2 

,E 

0. 3 + + ++ '2 

\ABC\ || 
t 1 ++ 

P ,E 
4 

,[1.5]£ 
0.3 +---+ 
\ABC\ 
+ + 
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, Ravel 

++ '2 
II 
+ + 

P ,[1.5]2 
2 1 2 

,[0.5]£ 

0.3 + + 

UBC | 

+ + 

+ + "2 

II 
+ + 

P ,[0.5]£ 
1 2 2 

Possible Errors Generated 



2 7 LIMIT ERROR (INTEGER TOO LARGE) 

2 8 AXIS RANK ERROR (NOT VECTOR DOMAIN) 

2 9 AXIS LENGTH ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 

2 9 AXIS LENGTH ERROR (NOT SINGLETON) 

30 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 

30 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 

3 AXIS DOMAIN ERROR (AXES NOT IN CONTIGUOUS ASCENDING ORDER) 
3 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

3 AXIS DOMAIN ERROR (INCORRECT TYPE) 

3 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) 
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t Represent 



t Represent 




Form 




AjB 




Left Argument Domain 


type 


Numeric 


Shape 


Any 


Depth 


or l (simple) 


Right Argument Domain 


Type 


Numeric 


Shape 


Any 


Depth 


or l (simple) 


Result Domain 




TVpe 


Numeric 


Rank 


( p p A) +p pS 


Shape 


( PA) ,pB 


Depth 


or 1 (simple) 


Implicit Arguments 




None. 




Description 





The dyadic t function (known as represent or encode) represents an array in 
any number system. The left argument specifies the number system; the right 
argument specifies the array to be represented. For example, to represent the 
decimal value 7 as a four-digit binary number, specify the following: 



2 2 2 2T7 



111 
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t Represent 

In the expression AtB, A can be considered as the representation rule to 
be applied to B . Each item of the vector A is defined in terms of the item 
immediately to its left. You can specify mixed bases in the left argument. 
For example, the represent function can express some number of inches in 
miles, yards, feet, and inches, or some number of milliseconds in days, hours, 
minutes, seconds, and milliseconds: 

Thus, in representing a number as miles, yards, feet, and inches, the left 
argument specifies, from right to left, 12 inches in 1 foot, 3 feet in 1 yard, and 
1760 yards in 1 mile. In the following example, a miles specification is not 
defined in terms of another quantity, so is printed in the miles column. 

nMILES, YARDS, FEET, INCHES 
1760 3 12T273125 
4 546 2 5 

nDAYS, HOURS, MINUTES, SECONDS, MILLISECONDS 
2<\ 60 60 1000T713732523 
8 6 15 32 523 

The following examples of base 3 conversions demonstrate the specification of 
different numbers of columns in the left argument and illustrate the way in 
which negative numbers are represented: 

3 3 3 3T17 ^PRODUCES 3'S COMPLEMENT OF 17 

12 2 

3 3 3 3T 17 ^PRODUCES 3'S COMPLEMENT OF "17 

2 10 1 

Another useful application of t is to return the integer and fractional portions 
of a number: 

J-e-8 2 3.7513 

o nx 

823 0.7513 

The following are more examples of the use. of the t function: 

A+§3 2p2 3 
B<-5 2 
U+R+AtB 

1 
1 
1 
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2 2 

2 2 

2 2 

2 

2 3 

2 3 2 



8 4 

1 6 

6 2 

9 

5 9 

3 2 



PR 

02 2p865 129 103 692 
D + X *■ 10 10 IOtC 



P* 



3 2 2 

3 1 2 i? Z 
8 6 5 

4 2 9 

10 3 

6 9 2 

2 2 2 2 2T13 
110 1 

2 2 2 2 2t~13 
10 11 



^PRODUCES 2'S COMPLEMENT OF 13 
^PRODUCES 2'S COMPLEMENT OF "13 



If 4 is a scalar, 4tB is the same as 4 | B with D CT«-o. Note that D CT is not an 
implicit argument to the represent function. 

Possible Errors Generated 



15 DOMAIN ERROR ( ENCLOSED ARRAY NOT ALLOWED) 
15 DOMAIN ERROR {INCORRECT TYPE) 
27 LIMIT ERROR (FLOATING OVERFLOW) 
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p Reshape 




Form 




ApB 




Left Argument Domain 


Type 


Nonnegative near-integer 


Shape 


Vector domain 


Depth 


or l (simple) 


Right Argument Domain 


TVpe 


Any 


Shape 


Any 


Depth 


Any 


Result Domain 




Type 


Same as right argument 


Rank 


P ,A 


Shape 


,A 


Depth 


- 


Implicit Arguments 




None. 




Description 





The dyadic p function creates an array of items from the right argument taken 
in row-major order and arranged in the shape specified by the left argument. 
For example: 

2 3 p i6 b2 ROWS, 3 COLUMNS 

12 3 
4- 5 6 
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If the right argument does not contain enough items to fill an array that has 
the shape specified by the left argument, the right argument is reused starting 
at its beginning: 

3 3 p 16 
1 2 3 

4 5 6 
1 2 3 

3p5 

5 5 5 

If the right argument has more items than are required for an array that has 
the shape specified by the left argument, the extra items are ignored: 

2 2 p 16 

1 2 
3 H 

Note that the right argument may be any type and shape (it is, in effect, 
raveled before it is reshaped): 

D<-B-<-3 5p'STAN SAM STEVE' 
STAN 
SAM 
STEVE 

20pB 
STAN SAM STEVESTAN 

For arguments A and B , if s is empty, A must contain at least one value, and 
the result is empty with the shape , A . For example: 

D«-i?«-2 p 1O 

(APL outputs a blank line) 

PR 

2 

If A is empty, the result is a scalar whose value is the first item of B in 
row-major order; formally expressed: 

(iO)pfi ++ ' ' pB <-+ ( ,B) iUIOl 
For example: 

(i0)p5 7 9 
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p Reshape 

Further examples: 

B+VAN+'ABC (12 3 4) 1.2 (c,3) 
+ + + + 1.2 + + 

USC | 1 1 2 3 M- 1 |+-+| 

+— + + + I I3|| 

+ + 

pVAN 
4 

B+VAN+2 2 p VAN 

+ + + + 

\ABC\ |1 2 3 *#- 1 

+ — + + + 

+ — + 

I+-+I 

II3II 

+ + 

pVAN 
2 2 

D-f-(iO) p VAN rEMPTY LEFT ARGUMENT 

+ — + 

Use | 
+ — + 

Possible Errors Generated 

9 RANK ERROR ( NOT VECTOR DOMAIN) 

10 LENGTH ERROR 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

15 DOMAIN ERROR (NEGATIVE NUMBER NOT ALLOWED) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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cj) and e Reverse 
Form 



<t>B <t>[if]B eB e[JGB 

$ is formed with o and I 
e is formed with o and - 



Argument Domain 



type 


Any 


Shape 


Any 


Depth 


Any 


Result Domain 




Type 


Same as argument 


Rank 


PpB 


Shape 


PS 


Depth 


^B 


Implicit Arguments 




None. 




Description 





The monadic <(> function returns the items of the argument array in reverse 
order along the relevant axis. You specify the axis to be reversed in square 
brackets. For example: 

1 2 3 t 
5 6 7 8 

e[l]4 
5 6 7 8 
1 2 3 t 

H2]i4 
4 3 2 1 
8 7 6 5 
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<|> and e Reverse 

If you do not specify an axis, $ reverses the items along the last axis, and e 
reverses the items along the first axis. For example: 

D<-03 3pi9 
1 2 3 
4 5 6 
7 8 9 

eG 
1 8 9 
4 5 6 
1 2 3 

<S>G 

3 2 1 
65 I 
9 8 7 

The following reverses a matrix along both axes simultaneously: 

Q<-Z<-2 3pi6 
1 2 3 

4 5 6 

<|>eX 
6 5 4 
3 2 1 

For singleton, vector, or empty arguments, both 4> and e return the same 
value. For an empty array or singleton, they return the original argument; for 
a vector, they return the items of the vector in reverse order. For example: 



4>5 
e5 

<M 

ij>l 1 lp6 



(APL outputs a blank line) 



<(>i5 
5 4 3 2 1 

ei5 
5 4 3 2 1 
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$ and e Reverse 



Note that reverse is not the same as transpose: 

Q-<-J<-2 3pl 2 3 H 5 6 
12 3 
H 5 6 

1 k 

2 5 

3 6 

Further examples: 

r>AfIZZ-«-2 H p 'ABC "1 2 <XYZ< 4 (c,3) 100 
+— -+ "1 2 
\ABC\ 

+ + 

+ + 1 + + 100 

\XYZ\ |+-+| 

+ — + l|3|| 

I+-+I 

+ + 

e[l]AfIZZ 
+ + 4- + + 100 

ixrzi I+-+I 

+— + I I 3 [ I 

I+-+I 

+ + 

+---+ "1 2 
\ABC\ 

+ + 

<t>L2]AfJZZ 
2 "1 +---+ 

\ABC\ 
+ — + 

100 + + 4 + + 

I+-+I \ITZ\ 
||3|| + — + 
I+-+I 

+ + 

tyeMIZZ 

100 + + 4- + + 

|+-+| \XYZ\ 
l|3|| + — + 

I+-+I 

+ + 

2 "1 +---+ 
\ABC\ 
+ — + 
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Possible Errors Generated 

2 7 LIMIT ERROR {INTEGER TOO LARGE) 

28 AXIS RANK ERROR ( NOT VECTOR DOMAIN) 

29 AXIS LENGTH ERROR (NOT SINGLETON) 

30 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 
30 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 

30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

30 AXIS DOMAIN ERROR (INCORRECT TYPE) 

30 AXIS DOMAIN ERROR (NOT AN INTEGER) 

30 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) 



1-144 APL Reference Manual 



Primitive Mixed Functions 

cj> and e Rotate 



(t> and e Rotate 
Form 

A$B AfylKlB AeB AelKlB 

<t> is formed with o and | 
e is formed with o and - 

Left Argument Domain 

Type Near-integer 

Shape Conforms to right argument (p4) = (pB)[ip p B ) ~ ) £] 

Depth or l (simple) 

Right Argument Domain 



Type 


Any 


Shape 


Any 


Depth 


Any 


Result Domain 




Type 


Same as right argument 


Rank 


PPB 


Shape 


PB 


Depth 


sB 


Implicit Arguments 




None. 




Description 





The dyadic § or e function rotates items along the relevant axis of the right 
argument in a way specified by the left argument. The rotation is cyclical and, 
for each axis, continues for the number of places specified by the corresponding 
item in the left argument. If the left argument is positive, the shift is to the 
left; if it is negative, the shift is to the right. For example: 
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4> and e Rotate 

3+i5 

t5123 

~3<|>i5 
3 1+512 

The axis to be rotated must be specified in square brackets, as in the following 
example: 

D-M+3 5pil5 
12 3 1+5 

6 7 8 9 10 
11 12 13 14 15 

2 1 i+<K2]yl 
3 1+512 

7 8 9 10 6 

15 11 12 13 1U 

2 10 2 3<t>[l]4 

11 7 3 14 5 
1 12 8 4 10 
6 2 13 9 15 

If no axis is specified, 4> rotates the items along the last axis, and e rotates the 
items along the first axis: 

D«-G-<-2 i+pi8 

12 3 4 

5 6 7 8 

2 l<t>G 
3 4 12 

6 7 8 5 

1 2 leff 
5 2 3 8 

16 7 4 

Note that, in general, the shape of the left argument must be the same as the 
shape of the relevant axis in the right argument. If the left argument is a 
singleton, it is extended to conform to the relevant axis of the right argument. 
For example: 

24>2 5pil0 
3 4 5 12 

8 9 10 6 7 
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Further examples: 

D+MIZZ+2 t p 'ABC "1 1 <XYZ' H (c,3) 100 

+ --- + "1 1 
UBC| 

t + 

+ + 4 + + 100 

\XYZ\ |+-+| 

+ — + II3II 

+ + 

i 3 <t> mu 

~i i +---+ 

\ABC\ 

+ — + 

100 + + t + + 

+— + ION 
I+-+I 

+ — + 

"1 1 1 «|> Lf]MIZZ 
+ + + + 100 

1 mi I+-+I 
+— + ION 

+ — + 
+---+ 4 "i i 

\ABC\ 
+ — + 

"1 1 1 e MIZZ 
+ + + + 100 

\nz\ I+-+I 

+ — + II3M 

+ + 

+---+ H '1 1 

\ABC\ 

+ + 

Possible Errors Generated 

9 RANK ERROR (RANKS DIFFER BY MORE THAN ONE) 

10 LENGTH ERROR (SHAPES OFF AXIS DO NOT MATCH) 
15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 
15 DOMAIN ERROR (INCORRECT TYPE) 
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15 DOMAIN ERROR (NOT AN INTEGER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 

28 AXIS RANK ERROR (NOT VECTOR DOMAIN) 

2 9 AXIS LENGTH ERROR (NOT SINGLETON) 

30 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 

30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

3 AXIS DOMAIN ERROR (INCORRECT TYPE) 
30 AXIS DOMAIN ERROR (NOT AN INTEGER) 

3 AXIS DOMAIN ERROR (RIGHT ARGUMENT HAS WRONG RANK) 
30 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) 
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p Shape 
Form 



PB 



Argument Domain 



Type 


Any 


Shape 


Any 


Depth 


Any 


Result Domain 




Type 


Nonnegative integer 


Rank 


l 


Shape 


PPS 


Depth 


1 (simple) 


Implicit Arguments 




None. 





Description 

The monadic p function returns a vector of nonnegative integers that represent 
the lengths of each of the axes of the argument array. 

If the argument is a vector, APL returns an integer vector that represents the 
number of items in the vector: 

A+2 1 6 8 

PA 
4 

B+'ABCDEF' 

PB 
6 

P.9 
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If the argument is a matrix, APL returns the number of rows and columns: 

D+At-2 3p i 6 
12 3 
4 5 6 

PA 
2 3 

If the argument is a scalar, APL returns an empty numeric vector: 

(APL outputs a blank line) 

You can use the shape function to determine an array's rank. Because the 
shape function returns one item for each axis of the array, the shape of shape 
is an integer vector that represents the number of axes in the array: 





Q+A+5 6pi 


.30 




1 


2 3 ^ 5 


6 




7 


8 9 10 11 


12 




13 


14 15 16 17 


18 




19 


20 21 22 23 


24 




25 


26 27 28 29 
pA 


30 




5 E 


PPA 






2 








Further examples: 






U*-Vi-'XY' 


(12 3)' 


1 


+-- 


•+ + + 






\XY\ |1 2 3| 






+ -- 


■+ + + 

PV 






3 










OB"- (2 


P5)C ')( 


•0) 


+ + 


++ 






II 


II 






II 


+ + 






++ 









pB 
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U+M+2 3 p 1 (") 'ABC 2 h 

1 ++ + + 

II \ABC\ 
++ + — + 

"2 4 

pM 

2 3 

p p M 
2 

Note that for alls: pppB <-+ ,1 

Possible Errors Generated 

None. 
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£ Subset 




Form 




AsB 




£ is formed with c and _ 


Left Argument Domain 


Type 


Any 


Shape 


Any 


Depth 


Any 


Right Argument Domain 


Type 


Any 


Shape 


Any 


Depth 


Any 


Result Domain 




Type 


Boolean 


Rank 





Shape 


i o (scalar) 


Depth 


(simple scalar) 



Implicit Arguments 

D CT (determines comparison precision) 

Description 

The dyadic c function determines whether the right argument contains all 
the items in the left argument. The result is a Boolean scalar: true, if the left 
argument is a subset of the right argument, and false if it is not. Duplicate 
items in either argument do not affect the result. For example: 
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|>/M 1 p 23 51+ 98 31+ 98 17 98 32 78 65 12 23 
23 5i+ 98 3"+ 
98 "+7 98 32 
78 65 12 23 

As i 100 
1 

Ac 1 90 


The £ function compares items in terms of the match (= ) function, which 
uses the value of Q CT. Because match allows mixed-type arguments, you can 
compare characters with numbers. However, such a comparison is always 
false, so that if you use mixed-type arguments for dyadic 5 , the result will be 
zero. For example: 

'23 2i+ 25'c 22 23 21 25 26 


Further examples: 

D<-F<-0 'AB< (1 2 3) 

+--+ + + 

\AB\ |1 2 3| 
+ --+ + + 

D+tft-2 2 p (1 2 3) '0' MB' M' 

+ + 

U 2 3| 

+ + 

+— + A 
\AB\ 
+ --+ 

V c M nSOTE CHARACTER AND HUMERI C ZEROS 



Note that the following definition applies: AsB +•-»■ a/ ,AeB 



Possible Errors Generated 

None. 
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+ Take 



Form 



A\B A+LKJB 

Left Argument Domain 



Type 


Near-integer 


Shape 


Vector domain 


Depth 


or i (simple) 


Right Argument Domain 


Type 


Any 


Shape 


Any 


Depth 


Any 


Result Domain 




Type 


Same as right argument 


Rank 


( p ,a) rpps 


Shape 


I , A (if no explicit axis) 


Depth 


- 


Implicit Arguments 




Fill item 




Description 





The dyadic + function builds an array by taking a specified number of items 
from an existing array. Each item in A corresponds to an axis in B . The value 
of each item in A specifies how many items to take from the axis. Thus, for 
A\B, item A[K1 is used to take values along the K th axis of B . 

If an item in A is a positive integer n, APL takes the first n items from the 
appropriate axis of B . If an item in A is negative, APL takes the last n items 
from the appropriate axis of B . 
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1 2 

3 4 



i?<-l 2 3 4 

2+i? RT^ifs rasr rwo irms of i? 

_ 2ti? hmjj L^sr r</o items of r 



Unless the right argument is a scalar, the number of items in A must equal 
the rank of B (p , A must equal ppB). (When the right argument is a scalar, it 
is extended to be a singleton of the appropriate rank.) If you use the axis form 
( [ K ] ), the number of items in A must equal the length of K . (Examples of axis 
form are presented at the end of this section.) Thus, if the right argument is a 
matrix, the left argument must have two values: 

Q*-R-<-3 3pi9 
12 3 
4 5 6 
7 8 9 

aLEFT ARG MUST BE LENGTH 2 
2fR 
10 LENGTH ERROR [LEFT LENGTH NOT EQUAL TO RIGHT RANK) 
2+i? 

A 

rTAKE THO ITEMS ALONG EACH AXIS 
2 2 + i? 
1 2 
4 5 

If the value of an item in A is greater than the length of the corresponding axis 
of B , APL pads the result array with fill items. This operation is known as 
overtake. For example: 



NUM+l 2 3 
CHA--'ABC< 



5+NUM 
12 3 



(5+CHA),<X' 
ABC X 



^OVERTAKE NUM, FILL ITEMS ARE ZEROS 



nOVERTAKE CHA, FILL ITEMS ARE BLANKS 
^CATENATE X TO SHOW END OF FILL ITEMS 



The fill items are determined by the prototype of each vector along the relevant 
axis. This is important for arrays of rank 2 or more because the fill item for 
a given position depends on the prototype of that particular column, row, or 
plane. The following expressions describe such an operation. Note where the 
fill items are blanks and where they are zeros. (Because the array M is simple, 
all the fill items are scalars. If M were enclosed, some of the fill items might 
also have been enclosed.) 
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□<-#-<- 2 3p 1 'A ! 


2 'fl' 1 5 


1 A 2 






B 1 5 


pM 




2 3 


^OVERTAKE 


« 4I0JVC FIRST AXIS 




^PROTOTYPE 


BASED ON VECTORS ALONG FIRST AXIS 




1+[1]M 




14 2 






B 1 5 
















p4+[l]M 


aFIRST AXIS IS CHANGED 


1 3 


5 + [2]M 


^OVERTAKE M ALONG 2ND AXIS 


1 A 2 







B15 


p5t[2]M 


ftlND AXIS IS CHANGED 


2 5 


1 5+M 


^OVERTAKE M ALONG BOTH AXIS 


1 A 2 







B 4 5 




















nBOTH AXIS ARE CHANGED 


1 5 







Note that if A is positive, any needed fill items are placed at the end of the 
result array. If A is negative, any needed fill items precede the result array. 
For example: 

6+12 21 36 18 nFILL ITEMS AT END OF RESULT 

12 21 36 18 

(10+ 'TEST'),'X< ^CATENATE X TO SHOW END OF FILL ITEMS 

TEST X 

"6+12 21 36 18 rFILL ITEMS AT BEGINNING OF RESULT 

12 21 36 18 

"10+ 'TEST' nFILL ITEMS AT BEGINNING OF RESULT 

TEST 

If the rank of the right argument is greater than 1, the result array is called 
a corner of the argument array. The origin of the corner is determined by the 
signs of the items of the left argument. For example, if the right argument is a 
matrix, there are four possible corners as shown in Figure 1-1. 
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Figure 1-1 Argument Corners Selected by Take Function 

► Axis 2 -« 



+ - 



Axis 1 

A 



t 

Axis 1 



-► Axis 2 ■+- 



NU-2233A-RA 



In the following example, note how the order of the signs in the left argument 
determines the corner selected from the matrix right argument: 



O+A+3 3pi9 



1 2 3 

4 5 6 

7 8 9 

1 2 

4 5 

5 6 

8 9 

4 5 
7 8 

2 3 

5 6 



2 2+4 



"2 2+4 



"2 2+4 



2 "2+4 



If the left argument contains a o , then, for arguments A and B , A + B returns 
an empty array with shape , | A. For example: 



4+2 3 + 2 3 3p 1 18 

P4 



2 3 



If the left argument is empty, the right argument must be a scalar, and the 
result is the right argument. 
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If the right argument is a scalar, it is extended to a singleton with a rank equal 
to the length of the left argument. For example: 

~2 3 + 5 


5 

Note that for any array A, = l + p A is true if A is numeric and false if A is 
character. 

When you use + with an axis argument, if is a vector of axis numbers 
whose lengths are determined by corresponding items of the left argument, 
A . Formally, + with an axis argument can be described by the following: 

z*-pB« ZLK1 ■*- A o Z *■ Z+B 

The value for K must be in the vector domain, and each item must be a near- 
integer in the set i p p B. Therefore, the values of if are JO-dependent. The 
items may be in any order, but they may not be duplicated. The length of K 
must be less than or equal to the rank of the right argument, and it must 
match the length of A . 

The value for K does not have to specify all the axes in B . APL determines the 
lengths of any missing axes by the lengths of the corresponding axes of B . This 
means that you can take rows or columns of a matrix without specifying the 
length of the other axis. For example: 





n«-4<-8 5pi40 


1 2 


3 


4 5 


6 7 


8 


9 10 


11 12 


13 


14 15 


16 17 


18 


19 20 


21 22 


23 


24 25 


26 27 


28 


29 30 


31 32 


33 


34 35 


36 37 


38 


39 40 




3 • 


t[l] A 


1 2 


3 


4 5 


6 7 


8 


9 10 


11 12 


13 


14 15 




"2 


+ [2] A 


4 5 






9 10 






It 15 






19 20 






24 25 






29 30 






34 35 






39 40 







fiTAKE 3 ROWS OF A 



aTAKE THE LAST 2 COLUMNS OF A 
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3 H +[2 1] A fiTAKE 4 RONS, 3 COLUMNS OF A 

1 2 3 

6 7 8 

11 12 13 

16 17 18 

QIO +■ 

4- 3+[0 1] 4 sM£ 4 flOWS, 3 COLUMNS OF A 

1 2 3 

6 7 8 

11 12 13 

16 17 18 

Qi-WRLHl 2 3) 'ABC 

+ + + + 

|1 2 3 | \ABC\ 

+ + + + 

StURL ^OVERTAKE TO SHOW FILL ELEMENT 

+ + + + + + + + 

|1 2 3| \ABC\ |0 | | 0| 
t + + + + + + + 

Possible Errors Generated 



9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (LEFT LENGTH NOT EQUAL TO RIGHT RANK) 
15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 

2 7 LIMIT ERROR ( VOLUME TOO LARGE) 

2 9 AXIS LENGTH ERROR (LEFT ARGUMENT HAS WRONG LENGTH) 

30 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 

30 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 

30 AXIS DOMAIN ERROR (DUPLICATE AXIS NUMBER) 

30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 
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30 AXIS DOMAIN ERROR (INCORRECT TYPE) 

30 AXIS DOMAIN ERROR (NOT AN INTEGER) 

2 8 AXIS RANK ERROR (NOT VECTOR DOMAIN) 

30 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) 
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§ Monadic Transpose 
Form 



isjfl 




$ is formed with o and \ 


Argument Domain 




Type 


Any 


Shape 


Any 


Depth 


Any 


Result Domain 




Type 


Same as argument 


Rank 


PPS 


Shape 


4>PB 


Depth 


= B 


Implicit Arguments 




None. 




Description 





The monadic <s> function transposes the axes of an array; thus, is; B is B with 
the order of the axes reversed. For example, if the argument is a matrix, is? 
exchanges rows and columns: 



D-M-i-2 3pi6 
1 2 3 

IS 6 

M 

1 it 

2 5 

3 6 



pU 



3 2 
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If the rank of the argument is less than 2, the function has no effect: 

A+l 2 3 4 5 
U 
1 2 3 4 5 

In the next example, a rank 3 array is transposed: 

Q«-Bi-2 3 Up 1 8 
12 3 4 
5 6 7 8 
12 3 4 

5 6 7 8 

1231 
5 6 7 8 

1 5 

5 1 

1 5 

2 6 

6 2 

2 6 

3 7 

7 3 

3 7 

4 8 

8 4 
4 8 

pi}B 
4 3 2 

Further examples: 

Q-<-MIZZ-<-2 4 p MAC "1 1 <X1Z< 4 (c,3) 100 
+ -— + "1 1 

\ABC\ 

+ + 

+ + 4 + + 100 

\UZ\ |+-+| 

+— + I I 31 I 

I+-+I 

+ + 
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muz 
+ — + + — + 

\ABC\ \XYZ\ 
+ + + — + 







+ + 

II3II 

I+-+I 

+ + 

100 
p MIZZ 



1 

2 4 

H 2 

Note that $ B 



pIsjWJZZ 



(<t>pB)*jB 



Possible Errors Generated 

None. 
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§ Dyadic Transpose 
Form 



AtstB 

is; is formed with o and \ 


Left Argument Domain 


Type 

Shape 

Depth 


Nonnegative near-integer 
Vector domain 
o or l (simple) 


Right Argument 


Domain 


Type 

Shape 

Depth 


Any 
Any 
Any 


Result Domain 




Type 
Rank 


Same as right argument 

RANK*- r IA +-UIO 


Shape 
Depth 


( l+pi4) + L/( ( i RANK) o . 



=A) x (RANK,pA)ppB 



Implicit Arguments 

A§B when Qio +■ l is identical to ( l + A) §B when QIO +- 

Description 

The dyadic is; function permutes the axes of the right argument in a way 

specified by the left argument. 

The shape (length) of the left argument must equal the rank of the right 
argument; thus, one item of the left argument is associated with each axis of 
the right argument. In general, the item in the left argument specifies the 
position to be assumed by the associated axis in the result array. For example: 
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D<-4-<-2 3 4p 1 24 
12 3 4 
5 6 7 8 
9 10 11 12 

13 14 15 16 
17 18 19 20 
21 22 23 24 

PA 
2 3 4 

D«-B<-1 3 2M 

1 5 9 

2 6 10 

3 7 11 

4 8 12 

13 17 21 

14 18 22 

15 19 23 

16 20 24 



2 4 3 
2 4 3 



(pA)ll 3 2] 



Note that the shape of the result of the is; function is equal to the shape of its 
right argument subscripted by its left argument. 

The values in the left argument must be less than or equal to the rank of the 
right argument; thus, if the right argument's rank is 3 , then 1,2, and 3 are 
the only permissible values in the left argument (when Q 10 is l ). However, 
there is one exception: if the right argument is a scalar, then either l (or if 
D 10 is ) or i is permissible as the left argument; the value returned is the 
value of the scalar right argument. 

You may repeat values in the left argument. When you do, the result is a 
diagonal slice of the right argument. For example: 
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X<-D+-2 H Up'* * * *' 

* 



* 

1 2 2W 
**** 

**** 

2 1 1W 
** 

** 
** 

y-*-D <_ 2 n up '****- 
** * * 



1 1 24)7 
**** 

**** 

2 2 i$y 

** 
** 
** 
** 

Z+Q<-2 H 4p i* — * — -* — -*- 

* 

* 

* 

* 



1 2 li?Z 
**** 
**** 
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2 i mi 



** 
** 

** 



When you repeat values in the left argument, they must form a dense 
sequence; that is, in counting from 1 (or if □ 10 is ) to the largest item 
you specify, no number may be left out. 

Note that dyadic is; is sometimes the same as monadic S( . Expressed formally, 
this means <s B «--* ( <j> p B ) is> B. For example: 



D-<-4-<-2 3pi6 



1 2 3 

156 

1 t 

2 5 

3 6 

1 4 

2 5 

3 6 



2 1M 



Table 1-6 lists transpositions for a variety of arrays: V is a vector, M is a 
matrix, and A is any array. 



Table 1-6 Dyadic Transpose Definitions 



Expression 



Shape of r 



Definition 



i?«-l 2§M pM 

R+2 Us>M ( pM) [2 1] 

R-l lisjW L/pM 

Rf-1 2 3§A pA 

R*-l 3 2§A ( pA) [1 3 2] 

i?-<-2 3 1M ( pi4) [3 12] 

i?<-3 1 2isj A ( pA) [2 3 1] 

i?-l 1 2^^ ( [/ ( pi) [1 2] ) , (p4) [3] 



R+V 

R*-M 

RH; J] ■«-#[ J; I] 

i?[ I] •<-«[!; I] 

RLI; J;K1 --AH; K; J] 
R\_I; J;n--AIJ;K; I] 
i?[I; «/; n+ALK; I; J] 
/?[!; J] "-All i I; Jl 

(continued on next page) 
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Table 1-6 (Cont.) Dyadic Transpose Definitions 



Expression Shape of R Definition 

R+12KHA ( L/ ( pA) [1 3] ) , (pi4) [2] RL I; Jl +A [ I; J; I] 

^2 1 1M ( L/ (pii) [2 3] ) , ( Pi4) [1] fl[I; Jl+ALJiI'.Il 

fi+1 i 1M L/p4 i?[I] ^i4[I; I; I] 



Further examples: 



U+MIZZ-i-2 Up ('ABC') ~1 1 ('irz 1 ) 4 (c,3) 100 
+---+ "1 1 
\ABC\ 

+ + 

+---+ H +---+ 100 

+— + I |3|| 
I+-+I 

+ + 

2 1 1st MIZZ fiTHIS IS THE SAME AS MONADIC ft) 

+ — + + + 

\ABC\ \XYZ\ 
+ — + + — + 

H 

"1 +---+ 

I I 3| | 

+ + 

1 100 

U+MIC+2 2 2 p'AB' (1 20) 1 2 0" 'A' 'XYZ< 

+--+ + + 

MB | |1 20 I 

+ --+ + + 

1 "2 



++ 

II 
+ + 
+■ + 

\nz\ 

+ — + 
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1 2 2 MIC 
+-- + ~2 

\AB\ 
+-- + 

+---+ 

I mi 

+ — + 

2 1 1 WIC 
+--+ 

lAfll 
+ -- + 

'2 + --- + 
\XYZ\ 
+ + 

1 2 1 kMIC 
+ -- + 1 

\AB\ 
+ -- + 

++ + + 

II \XYZ\ 
++ + + 

2 1 2 Is, MIC 
+--+ ++ 

\AB\ II 
+--+ ++ 

1 +---+ 
\XYZ\ 
+ + 

Possible Errors Generated 



9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR {LEFT LENGTH NOT EQUAL TO RIGHT RANK) 
15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (LEFT ARGUMENT NOT DENSE FROM QUAD 10) 

15 DOMAIN ERROR (NOT AN INTEGER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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u Union 
Form 

AuB 

Left Argument Domain 



Type 


Any 


Shape 


Any 


Depth 


Any 


Right Argument Domain 


Type 


Any 


Shape 


Any 


Depth 


Any 


Result Domain 




Type 


Any 


Rank 


l 


Shape 


P u ( ,A) 


Depth 


1{=A,B 



Implicit Arguments 

D CT (determines comparison precision) 

Description 

The dyadic u function joins the two arguments and removes all duplicate 
items. The result is a vector that includes all the items from both arguments. 
For example: 

'ABCB< u 2 3p <DDEDCC< 
ABODE 

(2 3p445t33)ul232 

15312 

The u function compares the items in terms of the match (= ) function and 
eliminates duplicate items based on the value of Q CT. 
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Further examples: 

D<-V<-(c,l00) 'TTY< '99' 

+ + + — + +--+ 

I+---+I \TTY\ |99| 
I | 100 | 1 +---+ +--+ 

l+— +1 
+ + 

Q<-M-<-2 2 p 100 99 >TTY' 
100 99 

+---+ 
\TTY\ 
+ — + 

V u M 
+ + + + +--+ 100 99 

I+---+I | m| |99| 

1 1 1.00 t j +---+ +--+ 

l+— +1 

+ + 



Note that the following definition applies: A u B -<--»- u ( , A ) , ,B 

Possible Errors Generated 

None. 
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u Unique 
Form 



uB 



Argument Domain 



Type 


Any 


Shape 


Any 


Depth 
nAmoin 


Any 


Type 


Same as argument 


Rank 


l 


Shape 


Equal to number of unique items 


Depth 


ir = s 



Implicit Arguments 



D CT (determines comparison precision) 



Description 



The monadic u function removes duplicate items from an array. The result is a 
vector of the unique items in the argument. For example: 



D<- A *■ ? 3 4 p 7 

6 5 it 2 

7 2 6 2 
13 7 6 

u A 
6 5 4 2 7 13 

B *■ < DR. GRANT 1 <S CHEUING GUM' 

DR.G ANT'S CHEWIUM 
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The u function compares the items in terms of the match (= ) function and 
eliminates duplicate items based on the value of Q CT. For example: 

OCT 
IE 15 

u4 it-5£~16 
H 

Note that the following definition applies: u B+--+ ( (Bifl) = ipB) /B+,B 

Possible Errors Generated 

None. 
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~ Without 
Form 

A ~ B 

Left Argument Domain 



Type 


Any 


Shape 


Any 


Depth 


Any 


Right Argument Domain 


TVpe 


Any 


Shape 


Any 


Depth 


Any 


Result Domain 




TVpe 


Any 


Rank 


1 


Shape 


p(~( ,A)eB) 1 ,A 


Depth 


- 



Implicit Arguments 

D CT (determines comparison precision) 

Description 

The dyadic ~ function returns all the items in the left argument that are not 
found in the right argument. Duplicate items in the right argument do not 
affect the result. Duplicates in the left argument are not removed unless they 
are specified in the right argument. For example: 
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RAMBLE*' RUN ON RUN ON RUN ON.' 

SQUISH*' ' rSQUISH CONTAINS A BLANK SPACE 

RAMBLE ~ SQUISH ^ELIMINATE THE BLANKS FROM RAMBLE 
RUNONRUNONRUNON. 

U+A+3 4p 56 78 105 137 49 329 97 235 142 105 56 59 
56 78 105 137 
19 329 97 235 
142 105 56 59 

A ~ ilOO 
105 137 329 235 142 105 

If your data represent sets, and you want to remove duplicates from your 
result, you can use the unique function along with the ~ function: 

A*3 4p 56 78 105 137 49 329 97 235 142 105 56 59 
U A ~ i 100 
105 137 329 235 142 

If the left argument is a subset of the right argument, the result is an empty 
vector. For example: 

U*B* 3 2 p 2 6 25 65 9 34 76 13 43 21 
2 6 
25 65 
9 34 

U B ~ 1 30 
65 34 

The ~ function compares items in terms of the match (= ) function, which 
uses the value of Q CT. Because match allows mixed-type arguments, you can 
compare characters with numbers. However, such a comparison is always 
false, so that if you use mixed-type arguments for dyadic ~ , the result will be 
equal to the left argument. For example: 

{A*' ABC) ~ B+'BA' 
C 

B ~ A 

(APL outputs a blank line) 

Note that the following definition applies: A~ B*+ ( - ( ,A) eS) / ,A 

Possible Errors Generated 

None. 
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1 .3 APL Operators 

APL operators take either functions or arrays as operands, and produce results 
called derived functions. 

Operators are either monadic or dyadic, but not ambivalent. Monadic 
operators bind to the left; that is, they take a left operand and not a right 
operand. Dyadic operators take a left and a right operand. Derived functions 
are either monadic, dyadic, or ambivalent (their classification depends on the 
arguments to the derived function and not on the valence of the operator). 

You can specify an axis when you use some of the operators. Because axis 
binds to the left, it must appear to the right of the operator. 

There are four APL primitive operators: slash (/ and / ), backslash (\ and \ ), 
each (" ), and dot (.). The following table describes the valence of the operators, 
the derived functions, and the valence of the derived functions. Note that A , B , 
f, and g are all operands where A and B are arrays, and f and g are functions. 



Operator 


Valence 


Derived Function 


Valence 


Slash 


Monadic 


Compress (A / and A/) 


Monadic 






Replicate (A/ andd/) 


Monadic 






Reduce ( f 1 and // ) 


Monadic 


Backslash 


Monadic 


Expand (A\ and A\) 


Monadic 






Scan f \ and f\ 


Monadic 


Each 


Monadic 


Item wise application (/" ) 


Ambivalent 


Dot 


Dyadic 


Inner product (f.g) 


Dyadic 






Outer product (° /) 


Dyadic 



Operators may accept functions or arrays for their operands. You can specify 
any valid function, including primitive functions, system functions, user- 
defined functions, and derived functions. (A derived function is a function 
resulting from the use of an operator.) 

Because derived functions may be operands for operators, it is possible to build 
sequences of operators to form function expressions. 

For example, you can use the inner product derived function (+ . x ) as the 
left operand to the slash operator (/ ). The result is the inner product reduce 
derived function, which allows you to perform matrix multiplication along a 
vector of matrices. Note that the left and right sides of the following expression 
are equivalent. However, the left side is more concise. The arrays Ml, M2, and 
M3 represent matrix arrays: 
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+ . x /Ml M2 M3 



Ml + . x M2 +. x M3 



The following example uses the outer product derived function ( ° . , ) as the 
left operand to the slash operator. The result is the catenate outer product 
reduce derived function, which in this case extends the monadic iota function 
( i ) to vector arguments to produce the odometer function: 

V+l 2 3 

,= »-. / l" V 

+ + + + + + + + + + + + 

111 1 | | 1 1 2 | |1 1 3| | 1 2 1 | |1 2 2| |1 2 3| 

+ + + + + + + + + + + + 

The following expression adds parentheses to show the binding action of the 
operator sequence: , => ((».,) / ) ( i " ) V 

Table 1-7 summarizes the operators and derived functions in greater detail, 
including the forms with axis. The subsequent subsections describe all the 
forms. 

Table 1-7 APL Operators 



Operator 



Name 



Meaning 



A compression/replication along the last axis of B 
A compression/replication along the K th axis of B 

A compression/replication along the first axis of B first axis 
of A 

The / reduction along the last axis of A 

The f reduction along the K th axis of A 

The f reduction along the first axis of A 

The application of monadic /"on each item of B 

The application of dyadic f on corresponding pairs of each 
item of A and B 

A expansion along the last axis of B 

A expansion along the K th axis of B 



A/B 


Slash 


Al IK1B 


Slash 


A{ IK1B 




A/B 


Slash 


f/A 


Slash 


fl LK1A 


Slash 


fi in A 




f/A 


Slash 


f"B 


Each 


Af'B 


Each 


A\B 


Backslash 


A\ IK1B 


Backslash 


A\ LK1B 





(continued on next page) 
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1 .3 APL Operators 

Table 1-7 (Cont.) APL Operators 



Operator Name Meaning 



A\B 


Backslash 


f\A 


Backslash 


A IK1A 


Backslash 


f\LK!A 




f\A 


Backslash 


A" .fB 


Dot 


Af.gB 


Dot 



Backslash A expansion along the first axis of B 
The f scan along the last axis of A 
The f scan along the K th axis of A 

The f scan along the first axis of A 
Outer product 
Inner product 



1.3.1 / and -/ Slash 

The monadic slash (/ and / ) operator takes a left operand and produces a 
monadic derived function. When the operand is an array, the derived function 
is either compression or replication. When the operand is a function, the 
derived function is reduction. 

1.3.2 \ and \ Backslash 

The monadic backslash (\ and \ ) operator takes a left operand and produces a 
monadic derived function. When the operand is an array, the resulting function 
is expansion. When the operand is a function, the result is scan. 

1 .3.3 . The Dot Operator 

The dyadic dot ( . ) operator takes a left and right operand and produces 
a dyadic-derived function. When the left operand is a jot ( ° ), the derived 
function is an outer product. When the left operand is a function, the derived 
function is an inner product. The right operand is always a dyadic function. 
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/ and / Compression and Replication 
Form 

A/B A/LK1B A-/-B A/LK1B 

{ is formed with / and - 

Left Operand Domain 

Type Near-integer 

Shape Vector domain 

Depth or l (simple) 

Right Argument Domain 

Type Any 

Shape Any 

Depth Any 

Result Domain (of derived function) 

Type Same as right argument 

Rank l r P P B 

Shape ((£-l)+pB),(+/l A) ,K*pB (for □ I0+- 1) 

Depth 

Implicit Arguments 

None. 

Description 

Compression and replication are monadic functions derived from the slash (/) 
operator. They build arrays by specifying the items to be deleted, preserved, 
or duplicated from an existing array, and by indicating where fill items are 
to be added in the new array. When items only are preserved or deleted, 
this is known as compression (the left operand is Boolean) . When items are 
d(uplicated, deleted, or filled, this is known as replication (the left operand is 
integer). You can also use the a REP system function to perform the compress 
and replicate operations (see Chapter 2 for more information). 
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For compression, each Boolean item in A corresponds to the position of an item 
in B . When 4 isl, the item in fi is preserved in the result array. When A is 
, the item in B is deleted from the result array. 

1 1 1 0/5 7 9 11 13 rTHIS IS COMPRESSION 
5 7 11 



For replication, each positive scalar and each zero in A correspond to the 
position of an item in B . Negative integers, which specify nil items, are not 
associated with explicit positions in B . When A is Boolean, the effects are the 
same as for compression (items are either preserved or deleted in the result 
array). When 1>A, the item in B is repeated A times in the result array. When 
A is negative, APL builds | A occurrences of the fill item into the new array: 

1 3 1 ~H 2 "2/5 7 9 11 13 rTHIS IS REPLICATION 

577790000 13 13 00 

If A contains only l s, the result is B itself; if A contains only o s, the result is 
an empty array. For example: 

1111 1/ x 5 
12 3 4 5 

0/i5 

(APL outputs a blank line) 

In general, the length of the relevant axis of B must equal the number of 
nonnegative items in A (( pfl) [#]-<->- + M> o). That is, you must specify an 
operation (either copy, drop, or replicate) for each item in the right argument. 
However, APL does perform singleton extension in certain conditions. If A is 
a positive singleton, it is extended to the length of B . (Negative values are not 
extended. When A is a negative singleton, B must be empty along the axis 
being replicated.) If B is a singleton, it is extended to the length of A . 

G+5 7 9 11 13 
A>1 1 1 

21 G ft SINGLETON EXTENSION ON LEFT ARGUMENT 

5 5 7 7 9 9 11 11 13 13 

K/5 uSINGLETON EXTENSION ON RIGHT ARGUMENT 



5 5 5 



D<*-3 lp9 

ptf 



(APL outputs a blank line) 



3 1 



2 3/M ^EXTENSION ON LAST (DEFAULT) AXIS 

(APL outputs a blank line) 
P (2 3/M) a THIRD AXIS EXTENDED 2 + 3 TIMES 



3 5 
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aNEXT EXPRESSIONS USE NEGATIVE SINGLETON IN LEFT ARGUMENT 
zTHE RIGHT ARGUMENTS MUST BE EMPTY ON APPLICABLE AXIS 
"2/ t 



"2/3 0p9 




















2/3 3 0p9 

















































G 


5 7 


9 11 13 




"2/G 


10 


LENGTH ERROR 




"2/G 




A 




"2/0 3p9 


10 


LENGTH ERROR 




"2/0 3p9 



ttLAST (DEFAULT) AXIS IS EMPTY 



nAGAIN, LAST AXIS IS EMPTY 



BRIGHT ARGUMENT NOT EMPTY 

nRIGHT ARGUMENT NOT EMPTY 

rWRONG AXIS IS EMPTY 

HURON G AXIS IS EMPTY 



If B is a vector, all four forms of the compression function have the same effect. 
If the rank of B is greater than 1, the form used determines which axis of the 
array is affected. 

For the forms A/ [if] B and A-f IK~\ B, the affected axis is axis K: 



Q*-B<-3 tpil2 
12 3 4 
5 6 7 8 
9 10 11 12 

1 1/[1]B 
12 3 4 
9 10 11 12 
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1 l/[i]B 
12 3 4 
9 10 11 12 

1 1 0/[2]fl 
1 3 
5 7 
9 11 

1 1 0/[2]B 
1 3 
5 7 
9 11 



The forms A/B and A+B affect the last and first axis of B, respectively: 

X+2 3pi6 
X 
12 3 

4 5 6 

1 1/X 
2 3 

5 6 

1 0/X 
12 3 

If A is empty, then B (after extension, if necessary) must have length along 
the relevant axis. 

If the left argument contains all negative numbers (indicating fill characters), 
then the applicable axis in the right argument must be empty, and the result 
will be the prototype of B repeated + / \ A times along the axis. If the applicable 
axis is not empty, APL signals LENGTH ERROR. For example: 

OB+-3 Op 5 

(APL outputs a blank line) 
"2 "3/B (^CORRECT AXIS IS EMPTY 





D-K>0 3p5 

(APL outputs a blank line) 
"2 ~3/C aINCORRECT AXIS IS EMPTY 

10 LENGTH ERROR 

"2 "3/C p INCORRECT AXIS IS EMPTY 

A 

APL inserts fill items that are determined by the prototype of each vector 
along the relevant axis. This is important for arrays of rank 2 or more because 
the fill item for a given position depends on the prototype of that particular 
column, row, or plane. The following expressions describe such an operation. 
Note where the fill items are blanks and where they are zeros. (Because the 
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array M is simple, all the fill items are scalars. If M were enclosed, some of the 
fill items might also have been enclosed.) 

fiCREATE M, A HETEROGENEOUS ARRAY OF RANK 3 
O+M+2 2 3p 1 M' 2 3 4 5 'A' 3 4 5 <B< 6 
1 A 2 
3 4 5 



4 3i+ 




5 B 6 






pM 


2 2 3 






COIf-1 "1 1 1 




nREPLICATE M ALONG LAST AXIS (DEFAULT) 




^PROTOTYPE BASED ON VECTORS ALONG LAST AXIS 




COL/M 


1 A 


2 


3 4 


5 


A 3 


4 


5 B 


6 




pCOL/M RLAST AXIS IS CHANGED 


2 2 4 






COL+1 '1 1 




C0L/121M 9REPLICATE M ALONG 2ND AXIS 


14 2 









3 15 




A 3 4 









5 B 6 






pC0L/L2]M A2JVD AXIS IS CHANGED 


2 3 3 






C0Z/[1]M rEXPAND M ALONG 1ST AXIS 


1 4 2 




3 i+ 5 














A 3 4 




5 B 6 






pCOL/LUM nlST AXIS IS CHANGED 


3 2 3 
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Further examples: 

Q+WRL<-(1 2 3) 'ABC 

+ + + + 

|1 2 3 | \ABC\ 
+ + + + 

1 1 0/WRL ^COMPRESSION 

+ + + — + 

|1 2 3 | \ABC\ 
+ + + + 

3 "2 2 '1/WRL ^REPLICATION 

+ + + + + + + + + + + + + + + + 

U 2 3 1 | 1 2 3| |1 2 3 1 |0 0| |0 0| \ABC\ \ABC\ |0 0| 
+ + + + + + + + + + + + + + + + 

Possible Errors Generated 

7 SYNTAX ERROR (NO DYADIC FORM OF DERIVED FUNCTION) 

9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

27 LIMIT ERROR (INTEGER TOO LARGE) 

28 AXIS RANK ERROR (NOT VECTOR DOMAIN) 

29 AXIS LENGTH ERROR (NOT SINGLETON) 

30 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 
30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 
30 AXIS DOMAIN ERROR (INCORRECT TYPE) 

3 AXIS DOMAIN ERROR (NOT AN INTEGER) 

3 AXIS DOMAIN ERROR (RIGHT ARGUMENT HAS WRONG RANK) 

30 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) 
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/ and / Reduction 
Form 

f/B f/LKlB f/B frLKlB 

i is formed with / and - 

Left Operand Domain 

Type Dyadic value-returning function 

Right Argument Domain 



Type 


Any 


Shape 


Any 


Depth 


Any 


jit Domain (of derived function) 


Type 


Depends on f 


Rank 


o r~ i + p ps 


Shape 


(pfl)[dppfl)-« 


Depth 


Depends on f 


icit Arguments 




None. 





Description 

Reduction is a monadic function derived from the slash (/ ) operator. To derive 
the reduction function, use any dyadic function as the operand (/"in the form) to 
slash, f can be a primitive dyadic function, a dyadic system function, a dyadic 
user-defined function, or a dyadic-derived function, f cannot be a user-defined 
operator. The result operates as if /"were applied between successive items 
along a specified axis of an array (B ). For example: 
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Q+i+16 

1 2 3 it 5 6 

1+2+3+4+5+6 



+ /I 
Ix2x3xltx5x6 

*/X 

</'A< 
</<AB< 



21 
21 
720 

720 

A 

1 

</<ABC< 
15 DOMAIN ERROR (INCORRECT TYPE) 
</<ABC< 

A 

The reduction of a scalar always returns the scalar itself. Thus, the last 
expression in the preceding example results in a DOMAIN ERROR because 
' B' < ' C evaluates to 1, and ' A ' < 1 is invalid because the data types do not 
match. 

Remember that APL evaluates expressions from right to left. For example: 

</l 2 3 


Here, APL evaluated 2< 3 and the result was 1. APL then evaluated l< 1 and 
returned 0. 

The result of the derived function has a rank that is one less than the rank of 
the original array (unless the original array is a scalar). Thus, the reduction of 
a matrix yields a vector, the reduction of a vector yields a scalar, and so forth. 

For the forms f/ [ if] B and // [ #] B, the applicable axis is axis K : 

D+4+2 4-p i 6 
12 3 4 

5 6 12 

+ /[2]4 
10 14 

+/L1U 

6 8 16 
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Further examples: 

D<-y<-(l 2 3) ("3 2 ~2) (~3 2 "2) (1 "1) 

+ + + + + + + + 

|1 2 3| |~3 2 ~2| |"3 2 "2 | |1 "1] 
+ + + + + + + + 

+ /Y 

+ + 

\~H 6 "2| 
+ + 

,/i3 ^SIMPLE ARG YIELDS NESTED RESULT 

+ + 

U 2 3| 
+ + 

If the length of the K th axis is 1, the result of the derived function is the 
original array with the K th axis removed: 

n+Ai-5 lp i 5 
1 
2 

3 
i+ 
5 

+ /LUA 
15 

+/L21A 
12 3 4 5 

The forms fl B and f{ B affect the last and first axes of B , respectively: 

U+A+-2 Up 1 6 
12 3 4 

5 6 12 

+ /A 
10 14 

+H 

6 8 4 6 

If the length of the applicable axis is 0, and all other axes have nonzero 
lengths, each result item is the identity function applied to the prototype of the 
argument, if one exists. The identity function for all scalar dyadic functions is 
p+f/ i o where p is the prototype of the right argument (p-f-t Op B) and /is the 
scalar dyadic function. The identity elements for the identity function of the 
scalar dyadic functions are listed in the following table: 
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Dyadic Function 



Identity Items for the Scalar Dyadic Functions 
Symbol Identity Item (f/ 1 o) 



Plus 


+ 





Minus 


- 





Times 


X 


1 


Divide 


^ 


1 


Power 


* 


1 


Residue 


1 





Maximum 


r 


Most negative representable number 
(" 1.7E38 approx) 


Minimum 


i 


Largest representable positive number 
(1.7E38 approx) 


Logarithm 


» 


None 


Combination 


i 


1 


Circle 


o 


None 


And 


A 


1 


Or 


V 





Nand 


A 


None 


Nor 


V 


None 


Less 


< 





Not Greater 


< 


1 


Equal to 


= 


1 


Not Less 


> 


1 


Greater 


> 





Not Equal 


* 






The identity functions for the nonscalar dyadic functions are listed in the 
following table. Note that P is the prototype of the argument B (defined 
formally as P«-+ op B). Any functions not listed (including system functions, 
user-defined operations, and derived functions from arbitrary operator 
sequences) do not have identity functions. 
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Identity Functions for the Nonscalar Dyadic Functions 


Dyadic Function 


Symbol 


Identity Function 


Reshape 


p 


P? 


Catenate 


, 


( ( "i+pP) ,o) P c ( Ci+pP) , o) P p 


Rotate 


* 


( ~ 14- p P) p 


Rotate 


e 


( 14- pP) p 


Transpose 


^ 


i p p P 


Pick 


3 


i 


Drop 


4- 


( PPP) PO 


Take 


+ 


pp 


Without 


~ 


i 


Matrix Divide 


a 


(ltpp)».=ltp? 



Possible Errors Generated 

7 SYNTAX ERROR (NO DYADIC FORM OF DERIVED FUNCTION) 

7 SYNTAX ERROR (NO DYADIC FORM OF FUNCTION) 

11 VALUE ERROR 

15 DOMAIN ERROR 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (FUNCTION HAS NO IDENTITY ITEM) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT A DYADIC FUNCTION) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 

28 AXIS RANK ERROR (NOT VECTOR DOMAIN) 

2 9 AXIS LENGTH ERROR (NOT SINGLETON) 

30 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 

30 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 
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30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

30 AXIS DOMAIN ERROR (INCORRECT TYPE) 

3 AXIS DOMAIN ERROR (NOT AN INTEGER) 

30 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) 
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Each 


Each 








Form 








f'B Af'B 








Left Operand Domain 






Type 


Any function 




Left Argument Domain 






Type 

Shape 

Depth 


Depends on 
Depends on 
Depends on 


the function f 
the function f 
the function f 




Right Argument Domain 






Type 

Shape 

Depth 


Depends on 
Depends on 
Depends on 


the function f 
the function f 
the function f 




Result Domain (of derived function) 




Type 
Rank 
Shape 
Depth 


Depends on the function f 
ppB (after singleton extension) 
p B (after singleton extension) 
Depends on the function f 




Implicit Arguments 








None. 









Description 

The monadic " operator (known as each) takes a function (f) as the left 
operand. The result is either a monadic or dyadic derived function (depending 
on the valence of/), /"can be a primitive function, a system function, a user- 
defined operation, or a derived function from an arbitrary operator sequence. 
The function /does not have to be a value-returning function. 
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When you use " , the action of a monadic / is applied to successive items 
of an array (B in the form), and the action of a dyadic /"is applied between 
corresponding pairs of items (A and B in the form). The action of /"is only 
applied to the top level of nesting in an enclosed array (" is not pervasive). 

B +■ 1 

C +■ i5 

D *■ 2 2 p 'ABCD' 

U <- E *■ B , (cC), cD affors (7S£ OF PARENTHESES 
H + + + ._ + 

|12 3 15| MB | 
+ + |CT>| 

+ -- + 

QE fiSHAPE OF E SHOWS A 3-ITEM VECTOR 

3 

p"E nSHAPE OF EACH OF E SHOWS SHAPE OF ALL ITEMS 

++ +-+ + + 

II |5| |2 2| 
++ +-+ + + 

S E nDEPTH OF E SHOWS ONE NESTING LEVEL 

2 

="E nDEPTH OF EACH OF E SHOWS DEPTH OF ALL ITEMS 

1 1 

D +■ E <- c£ 
+ + 

|t + + +--+| 

1 |12 3 4 5| \AB\ | 
| + + | CJ3 || 

I +--+I 
+ + 

p"p"£ aRAHK OF EACH ITEM OF E 

+ - + 

HI 
+ - + 

D +■ F *■ cE,E,E 
+ + 

|+ + + + + + | 

lit- + + +--+I h + + +--+I it + + +--+M 

II |12 3t5| \AB\\ | |123t5| \AB\ | | |1 2 3 1 5| \AB\\\ 
|| + + | CD || | + + {CDl | | + + |CT(|| 

II +-+I I +--+I I +--+H 
| + ++ ++ + | 

+ + 

PF aSHAPE OF F SHOWS IT IS NOW A SCALAR 

(APL outputs a blank line) 
= F (\DEPTH OF F SHOWS ENCLOSED ARRAY, 3 NESTING LEVELS 

4 
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iSHAPE OF EACH OF F SHOWS 1 VECTOR OF SHAPE 3) 



P F 



+ - + 
|3| 
+ - + 

p""F 
+ + 

|+-+ +-+ +-+| 
M3| |3| |3|| 
|+-+ +-+ +-+| 
+ + 



iSHAPE OF EACH/EACH OF F SHOWS 3 VECTORS OF SHAPE 3 



aSHAPE OF EACH/EACH/EACH OF F 



j + + + + + + 

||++ +-+ +---+I |++ +-+ +---+I |++ +-+ +---+I 
MM |5| |2 2|| HI |5| |2 2|| HI |5| |2 2| | 

jj++ + - + + +| |++ +-+ + +1 I ++ +-+ + +1 

j + + + + + +| 

+ + 

VZ+SH X 

uTHIS USER-DEFINED FUNCTION RETURNS A RESULT 

flSfl DETERMINES IF ARRAY X IS SIMPLE HOMOGENEOUS 

Z-K2> = Z)a (+Z)A.=Z<-t-"0p" > "X 

7 
SH 'A' 2 3 



[1] 
[2] 

[3] 
[4] 




1 

1 1 





SH i 5 

SH 2 2p<ABCD< 
SH (1 2) 3 
SH 'ABC 5 



The following example shows the use of system functions with the each 
operator. The example creates a vector of function definitions and then 
displays the canonical representation of each of the list of functions: 



F00 
1 + 2 



X <- 2 2p'F 2 
X 



Y +■ 2 3p 'F001+2 ' 
Y 



) FNS 
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UFX" X Y 
+-+ + + 

m \foo\ 

+ -+ + — + 

)FNS 
F F00 

QCR " 'F< 'F00' 

+ -+ + + 

|F| \F00\ 
|2| |1+2| 
+ -+ + + 

ubox" uvr" c[2]djvj; 3 

+ + + + 

I VF| I VFOOI 
|[1] 2 1 |[1] 1+2| 
I v I I V I 
+ + + + 



The next example shows the use of each to derive a dyadic function: 



X^' WENDY' 'STAN' 'PETER' 

X 

+ + + + + + 

\ WENDY \ \STAN\ \PETER\ 
+ + + + + + 

(^UALPHA) i" X 

+ + + + + + 

|4 2 3 1 5| |3 t 1 2| |2 1+ 1 5 3| 
+ + + + + + 

Y <- (it) (16) (i3) 

Y 
+ + + + + + 

1 1 2 3 M- 1 |123t56| |123| 
+ + + + + + 

2 1 3 f I 
+ + + + + + 

|3 H 1 2| |2 3 4 5 6 1| |1 2 3| 
+ + + + + + 



The next example shows each as part of a derived function: 



+ / (2 2pi"0(9 8 7) 
+---+ 24 
13 7| 
+ + 
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Possible Errors Generated 



9 RANK ERROR 

10 LENGTH ERROR 

40 OPERATOR DOMAIN ERROR (OPERAND TO EACH NOT A FUNCTION) 
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\ and \ Expansion 
Form 

A\B A\IK3B A\B A\£K1 B 

\ is formed with \ and - 

Left Operand Domain 



Type 


Near-Boolean 


Shape 


Vector domain 


Depth 


or l (simple) 


Right Argument Domain 


Type 


Any 


Shape 


Any 


Depth 


Any 


Result Domain (of derived function) 


Type 


Same as argument 


Rank 


lrpps 


Shape 


( p B ) [( x p p B ) ~ Kl and p , A on axis K 


Depth 


1\ = B 


Implicit Arguments 




None. 




Description 





Expansion is a monadic function derived from the backslash (\ operator. It 
builds an array by combining the items of an existing array with fill items. You 
can also use the D EXP system function to perform the expand operation (see 
Chapter 2 for more information). 

Each item in the operand (A in the form) is a Boolean scalar that corresponds 
to the position of an item in the right argument (B ). When A is l , APL inserts 
the corresponding item along the relevant axis of B into the result array. When 
A is o , APL inserts a fill item into that position in the result array. There 
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must be a l for each item along the relevant axis in the right argument, so 
that all the items in B appear in the result array. Any number of fill items 
may be included: 

U+LIS+12 13 15 
12 13 15 

7+10101 



nZEROS IN V DECIDE LOCATION OF FILL ITEMS 



V\LIS 
12 13 15 



A singleton right argument is extended along the axis to a length that matches 
the number of l s in the left argument: 

1 1\5 
5 5 

If the left argument is a singleton, APL signals an error: 

1\5 6 7 8 
10 LENGTH ERROR 
1\5 6 7 8 

A 

0\5 6 7 8 
10 LENGTH ERROR 

0\5 6 7 8 

A 

If the right argument is a vector, all four forms of the expansion function have 
the same effect. If the rank of the right argument is greater than 1, the form 
used determines which axes of the array are affected. 

For the forms A\ [ K] B and A\[K]B, the affected axis is axis K : 

B+A+2 3p i 6 
1 2 3 
H 5 6 

1 l\[l]/4 fiEXPAND ALONG 1ST AXIS 

12 3 

4- 5 6 
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1 1\[1]A ^EXPAND ALONG 1ST AXIS 

12 3 

it 5 6 

1 1 1\ [2]/ ^EXPAND ALONG 2ND AXIS 

10 2 3 
t 5 6 

1 1 1\[2]4 nEXPAND ALONG 2ND AXIS 

10 2 3 

4 5 6 

The forms A\B and A\B affect the last and first axis of B , respectively: 

X+3 9p ' *THISISANEXPANSIONEXAMPLE** ' 

X 
*THISISAN 
EXPANSION 
EXAMPLE** 

PX 
3 9 

7+11111011011 

V\X ^EXPAND X ALONG LAST AXIS 

*TEIS IS AN 
EXPAN SI ON 
EXAMP LE ** 

1 1 1U nEXPAND X ALONG FIRST AXIS 

*THISISAN 

EXPANSION 
EXAMPLE** 

When you expand an array, APL uses fill items that are determined by the 
prototype of each vector along the relevant axis. This is important for arrays 
of rank 2 or more because the fill item for a given position depends on the 
prototype of that particular column, row, or plane. The following expressions 
describe such an operation. Note where the fill items are blanks and where 
they are zeros. (Because the array M is simple, all the fill items are scalars. If 
M were enclosed, some of the fill items might also have been enclosed.) 

Q*-M<-2 2 3p 1 M' 2 3 <i 5 'A' 3 4 5 'B' 6 

1 A 2 
3 4 5 

A 3 4 

5 B 6 

pM 

2 2 3 

B00+1 1 1 
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nEXPAND M ALONG LAST AXIS [DEFAULT) 
PROTOTYPE EASED ON VECTORS ALONG LAST AXIS 
B00\M 
14 2 
3 4 5 

A3 4 
5 B 6 

pB00\M RLAST AXIS IS CHANGED 

2 2 4 

B0O+1 1 

B00\[2]M rEXPAND M ALONG 2ND AXIS 

1 A 2 



3 4 5 

4 3 4 


5 B 6 

pB00\[2]W *2ND AXIS IS CHANGED 

2 3 3 

B00\[1]M ^EXPAND M ALONG 1ST AXIS 

1 A 2 

3 4 5 




4 3 4 

5 B 6 

pB00\[l]Af fllSJ" 4JIS IS CHANGED 

3 2 3 

Note that the right argument may be empty: 

0\ i 


[K4*-0 0\ ' ' 

(APL outputs a blank line) 

P4 
3 

If the left argument is empty, the right argument (after extension, if necessary) 
must have length along the relevant axis. 

For a simple, homogeneous array A , the result of the expression = \ p A 
is 1 if A is numeric, and if A is character. For any array X , the result 
of the expression (2>a)* (+Z)A.=z<-+"op","XislifX is simple or 
homogeneous, and if X is either nonsimple or heterogeneous. 
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Further examples: 

U+WRL+d 2 3) ('ABC') 

+ + + + 

|1 2 3 | | ASC| 
+ + + + 

ion i\rai 
+ + + + + — + + + o 

|1 2 3 | |0 0| | ABC | |0 0| 

+ + + + + + + + 

Possible Errors Generated 



7 SYNTAX ERROR (NO DYADIC FORM OF DERIVED FUNCTION) 

9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR 
15 DOMAIN ERROR 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 
15 DOMAIN ERROR (INCORRECT TYPE) 
2 7 LIMIT ERROR (INTEGER TOO LARGE) 

2 8 AXIS RANK ERROR (NOT VECTOR DOMAIN) 

29 AXIS LENGTH ERROR (NOT SINGLETON) 

3 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 

30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 
3 AXIS DOMAIN ERROR (INCORRECT TYPE) 

30 AXIS DOMAIN ERROR (NOT AN INTEGER) 

3 AXIS DOMAIN ERROR (RIGHT ARGUMENT HAS WRONG RANK) 

30 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) 
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\ and \ Scan 
Form 

f<B flKlB f\B f\LKlB 

\ is formed with \ and - 

Left Operand Domain 

Type Dyadic value-returning function 

Argument Domain 



Array 


Any 


Type 


Any 


Shape 


Any 


Depth 


Any 


Result Domain (of derived functi 


Type 


Depends on / 


Rank 


ppB 


Shape 


PB 


Depth 


Depends on / 


Implicit Arguments 




None. 




Description 





Scan is a monadic function derived from the backslash ( \ operator. To derive 
the scan function, use any dyadic function as the operand if in the form) to 
backslash, f can be a primitive dyadic function, a dyadic system function, a 
dyadic user-defined function, or a dyadic-derived function from an arbitrary 
operator sequence. The result operates as if f were applied between successive 
items along a specified axis of an array (S ). Thus, a scan of an array works the 
same as a reduction, except that the scan returns the results as the function is 
applied to each successive group of items. 
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The result has the same shape as B . The first item of the result is always 
identical to the first item of B , and the last item is equal to the f reduction of 
B . For example: 

+ \3 4 5 
3 7 12 

As the function is applied to each successive group of items, APL evaluates the 
resultant expressions from right to left: 

-\1 2 3 4 
1 "1 2 ~2 

Here, APL returned the following: 

• The first item in the argument array 

• The result of the expression 1-2 

• The result of the expression 1-2-3 

• The result of the expression 1-2-3-4 

Note that APL treated each expression in the example independently; for 
example, the result of the expression 1-2 did not affect the evaluation of the 
expression 1-2-3. 

If B is an empty array, the result is an empty array. 

For the forms f\LKlB and f\ LK1 B, the applicable axis for the scan is axis K : 

Q+A+2 4-p i 6 

12 3 4 
5 6 12 

+ \[2]4 
1 3 6 10 

5 11 12 14 

+ \U1A 
12 3 4 

6 8 4 6 

The forms A B and f\ B affect the last axis and first axis of B , respectively: 
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D^<-2 4p i 6 
12 3 1 
5 6 12 

+ \A 
1 3 6 10 

5 11 12 1H 

+ \A 
12 3 1 

6 8 4 6 

Note that the scan operator is never applied if B has the length l . Thus, 
+ \ ' A ' <-->- ' A ' . Also note that for = \ ' AB ' ■*--*■ ' A ' , is heterogeneous, 
because the first item of the result would be a character ( ' A ' ), and the second 
item would be a number , the result of ' A ' = ' B ' . 

If the dyadic function specified with scan is one of the associative primitive 
functions (+ , x , L , l~ , < , and v for all arguments; = and * for Boolean 
arguments), APL uses an optimization that changes the way scan is computed. 
The definition of R+f\B (for vectors #[#] =/*/ KiBo) is changed as follows: 

K[l] = Bill 

RIK] = RLK-ll f BLK1 for Kel+ipB 

This optimized scan requires fewer operations than the traditional scan. 
Note that the result of an associative operation may differ slightly from the 
nonassociative approach, and you should use it carefully if your results require 
a high degree of precision. For example: 

A+1E6 ~1£6 1£"16 

A 
1000000 "1000000 1£~16 

+ \A 
1000000 IE 16 

+ /A 


Further examples: 

D<-l^(2 2 3) (2 1 0) 
+ + + + 

|2 2 3 | |2 1 0| 

+ + + + 

+ + + + 

|2 2 3 | | 2 1 0| 

+ + |2 1 0| 

I 

|2 1 0| 
12 1 0| 
+ + 
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p\3 2 1 rSIMPLE ARG YIELDS NESTED RESULT 

3 + + + + 

|2 2 2 | 111 1| 
+ + + + 

Possible Errors Generated 

7 SYNTAX ERROR (NO DYADIC FORM OF DERIVED FUNCTION) 

7 SYNTAX ERROR (NO DYADIC FORM OF FUNCTION) 

11 VALUE ERROR 

15 DOMAIN ERROR 

15 DOMAIN ERROR (INCORRECT TYPE) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 

2 8 AXIS RANK ERROR (NOT VECTOR DOMAIN) 

2 9 AXIS LENGTH ERROR (NOT SINGLETON) 

3 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 
30 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 

30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

3 AXIS DOMAIN ERROR (INCORRECT TYPE) 

3 AXIS DOMAIN ERROR (NOT AN INTEGER) 

3 AXIS DOMAIN ERROR ( SEMICOLON LIST NOT ALLOWED ) 

40 OPERATOR DOMAIN ERROR (NOT A DYADIC FUNCTION) 
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o . f Outer Product 
Form 

A° .fB 

Left Operand Domain 

Type Always jot ( ° ) 

Right Operand Domain 

Type Dyadic function 

Left Argument Domain 



Type 


Any 




Shape 


Any 




Depth 


Any 




Right Argument Domain 




Type 


Any 




Shape 


Any 




Depth 


Any 




Result Domain (of derived fu 


mcti 


Type 


Depends 


on/ - 


Rank 


( p p A) + 


ppB 


Shape 


(pA) , p 


B 


Depth 


Depends 


on/* 


Implicit Arguments 






None. 
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Description 

Outer product is a derived function that specifies an operation to be performed 
between every item of one array and every item of another array. In the 
expression R+-A ■> ,fB,R is an array that results from the application of the 
function f to every pair of items of A and B . f can be a primitive dyadic 
function, a dyadic system function, a dyadic user-defined function, or a dyadic- 
derived function from an arbitrary operator sequence. The function f does not 
have to be a value-returning function. 

In the following example, note how the outer product operator affects the 
operation of the primitive scalar function multiply: 

1 2 3x2 3 4 ^SCALAR PRODUCT APPLIES x TO EACH PAIR 
2 6 12 

aOUTER PRODUCT APPLIES x BETWEEN ALL ITEMS 

1 2 3«,»2 3 4 
2 3 it 
4 6 8 
6 9 12 

In the next example, the outer product operator affects the operation of 
the equal function so that each data item in the left argument is compared 
to each item in the right argument. Then, the reduction function (derived 
from the slash operator) is used to determine how many times each item 
in the left argument appears in the right argument. Note that the left 
argument determines the number of rows in the result, and the right argument 
determines the number of columns: 

G<-1 2 3 2 2 1 

(i3)°.=G rFIND THE LOCATIONS OF 1S.2S.AND 35 IN G 

10 1 
10 110 
10 

+/(i3)°.=G ftUSE REDUCE TO TOTAL THE ROWS 

2 3 1 

ftTHERE ARE TWO IS THREE 25 AND ONE 3 IN G 

Further examples: 

D+tf<-(l 2 3) 'ABC "2 

+ + + + ~2 

|1 2 3| \ABC\ 
+ + + + 
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(i2) ».= x 
+ + + + 

|1 1 |0 0| 

+ + + + 

+ + + + 

|0 1 1 |0 0| 
+ + + + 

D •<-!/•<- (2 2 3) (2 1 0) 
+ + + + 

|2 2 3 | |2 1 0| 

+ + + + 

W o.p W 

+ + + + 

|2 2 3 | |2 1 0| 

|2 2 3 J |2 1 0| 

I I I 

|2 2 3 | |2 1 0| 

|2 2 3 1 |2 1 0| 

+ + + + 

+ + + + 

II II 
II II 
II II 
++ ++ 

(i3) ».p "1 2 a SIMPLE ARGS YIELD NESTED RESULT 
+--+ +-+ +-+ 

m 121 i o i 

+--+ +-+ +-+ 
+ + + — + + — + 

|"1 "1| |2 2| |0 0| 
+ + + — + + — + 

+ + + + + + 

|"1 "1 "1| |2 2 2 | |0 0| 

+ + + + + + 

Possible Errors Generated 



7 SYNTAX ERROR (NO MONADIC FORM OF DERIVED FUNCTION) 

15 DOMAIN ERROR 

15 DOMAIN ERROR (INCORRECT TYPE) 

4 OPERATOR DOMAIN ERROR (NOT A DYADIC FUNCTION) 
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f . g Inner Product 

Form 

Af.gB 

Left Operand Domain 

Type Dyadic value-returning function 

Right Operand Domain 

Type Dyadic value-returning function 

Left Argument Domain 



Shape 




Any, inner axes of A and B must conform 


Depth 




Any 




Right Argument Domain 




Type 




Any 




Shape 




Any, inner axes of A and B 


must conform 


Depth 




Any 




Result Domain 


(of derived function) 




Type 




Depends on f and g 




Rank 




or - 2+ ( p p A) +p p B 




Shape 




( ~1+ pA) , 1+pfl 




Depth 




Depends on f and g 




Implicit Arguments 






None. 
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Description 



The derived function inner product produces the common algebraic matrix 
product of two arrays. The name inner product comes from the application 
of the function (g) along the inner axes of the two arguments, f and g can be 
a primitive dyadic function, a dyadic system function, a dyadic user-defined 
function, or a dyadic-derived function from an arbitrary operator sequence. 
(The inner axes are the last axis of the left argument and the first axis of the 
right argument.) For example: 

U*-A<-2 3pi6 
12 3 
"4 5 6 

D^B^i 3 
12 3 

A+.xB 
14 32 

aINNER AXES DO NOT MATCH IN NEXT EXPRESSION 
B+.*A 
10 LENGTH ERROR (LENGTHS OF INNER AXES DO NOT HATCH) 
B+.xA 

A 

In the preceding example, each item along the first axis of the right argument 
(in this case, S has only one axis) is multiplied by the corresponding item along 
the last axis of the right argument, and the products of each row are summed. 
The lengths of these inner axes must conform (in this case they are both 3). 
The shape of the result is the shape of A (2 3) catenated to the shape of B (3) 
without their inner axes. 

When each of the arguments has only one axis, the result is a scalar: 

( i 3 ) + . x i 3 

14 

When you want to perform the inner product with one object on itself, use 
transpose: 



D-M+-2 3p 1 6 



1 2 3 
4 5 6 

14 32 
32 77 



4+.x(s 
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You can also specify an inner product in which an operation other than 
multiplication is performed. Commonly, you might also use a . = (And Dot 
Equals), v .* (Or Dot Not equals), or * .* (Times Dot Star). Using this method, 
you can locate values containing specific characters or search for a row of one 
array in which all the items are equal to those in a column of another array. 
For example: 

r>B«-2 3 1 6 
3 

fiNEXT EXPRESSION COUNTS WHERE 2 AND 6 
2 6+.<B fl ARE < THE TWO ROWS OE EACH COLUMN IN B 



ONE 
THO 
SIX 
TEE 

k 3 

3 



D+M 3p 'ONETWO SIXTEEN' 

PX 

pY<-<SIX' fiFIND WHERE Y OCCURS IN SIX 



To be used in an inner product operation, the two arguments, denoted A and B , 
must conform to at least one of the following rules: 

• A or B is a singleton 

• The inner axes (the results of ~ 1 + p A and 1+pB) are equal 

• Either the last axis of A (~ 1+ p A) or the first axis of B (l+pB) equals 1 

If the first or third rule is true, then the corresponding argument is extended 
(through the process of singleton extension) so that the arguments have equal 
lengths along the matching axes. 

If ( o = ~i+p;4) ao= ltpB, but no other axes of A and B are equal to 0, then the 
inner product operator returns an array of identity items for the function f, as 
in reduction. 
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Further examples: 

[>G-<-l 3 p (1 2 3) ("2 1) "2 
+ + + + ~2 

|1 2 3| |"2 1| 
+ + + + 

G + .x iS) G 

+ + 

|9 8 lit | 

+ + 

nSIMPLE ARGS YIELD NESTED RESULT 
(i3) , .p i3 

+ + 

|1 2 2 3 3 3| 
+ + 

Possible Errors Generated 

7 SYNTAX ERROR (NO MONADIC FORM OF DERIVED FUNCTION) 

11 VALUE ERROR 

10 LENGTH ERROR (LENGTHS OF INNER AXES DO NOT MATCH) 

15 DOMAIN ERROR 

15 DOMAIN ERROR (FUNCTION HAS NO IDENTITY ELEMENT) 

15 DOMAIN ERROR (INCORRECT TYPE) 

10 OPERATOR DOMAIN ERROR (NOT A DYADIC FUNCTION) 
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[ ] Axis 

Form 

flKlB AftKlB 

Left Argument Domain 

Type Monadic or dyadic function 

Right Argument Domain 

Type Near-integer (floating for laminate and ravel, Any for user- 

defined operations) 

Shape Singleton (Vector for drop, enclose, disclose, ravel, 

take and all dyadic scalar functions, Any for user-defined 
operations) 

Depth o or i (simple), Any for user-defined operations 

Result Domain 

Type Same as left argument 

Implicit Arguments 

UIO(flK] when QI0+-1 is identical to fLK+ll when D 10*- o) 

Description 

Axis makes the function to its left apply to the axis specified by the value 
surrounded by brackets. The following functions and operators may be affected 
by axis: 

Catenate ( , and 7 ) 

Derived compress/replicate (/ and / ) 

Derived reduction (/ and / ) 

Derived expand (\ and \ ) 

Derived scan (\ and \ ) 

Disclose (=> ) 

Drop (+ ) 
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Enclose (<= ) 

Laminate ( , and 7 ) 

Monadic grade up (4 ) 

Monadic grade down (f ) 

Ravel ( , and T ) 

Rotate (<j> and e ) 

Reverse (<t> and e ) 

Take (+ ) 

UEXP 

DREP 

All dyadic scalar functions (see Table 1-1 in Section 1.1.1) 

User-defined operations 

The use of axis with these functions (and operators) is described in the 
individual explanations of the functions. For examples and further descriptions 
of axis with scalar functions, see Section 1.1. 

When you use axis with the T , / , \ , and e functions, the functions are 
equivalent to , , / , \ , and $ used with axis. The following list shows the 
definitions and equivalences of these symbols. Note the following: 

f represents either , , / , \ or $? 

g represents T , / , \ , or e 

A and B represent any arrays 

S is any scalar 

K is any axis 

D 10 is used to select the first axis of an array. 

gB <-- /ID 10] B 

fLKl B <--► gin B for all* 

fS <-->- flQIOl S «--»• g S ++ glOIOl S 

Ag B «"»■ A f CD 10] B 

Aft Kl B «-->- AglKl B for all K 

AfS +■-»- A f[ D 101 S ■<-+ Ag S ++ AglO 101 S 

Axis is □ 10-dependent; thus, all the functions named are Q 10 -dependent when 
they are affected by axis, except user-defined operations. 
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Possible Errors Generated 

28 AXIS RANK ERROR (NOT VECTOR DOMAIN) 

29 AXIS LENGTH ERROR (NOT SINGLETON) 

30 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 

30 AXIS DOMAIN ERROR (AXES NOT IN CONTIGUOUS ASCENDING ORDER) 

30 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 

30 AXIS DOMAIN ERROR (DUPLICATE AXIS NUMBER) 

30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

30 AXIS DOMAIN ERROR (INCORRECT OPERATION) 

30 AXIS DOMAIN ERROR (INCORRECT TYPE) 

3 AXIS DOMAIN ERROR (LEFT ARGUMENT HAS WRONG LENGTH) 

30 AXIS DOMAIN ERROR (NOT AN INTEGER) 

3 AXIS DOMAIN ERROR (RIGHT ARGUMENT HAS WRONG RANK) 

30 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) 



1-214 APL Reference Manual 



Primitive Mixed Functions 

«- Specification Function 



-«- Specification Function 
Form 

A^B Ain+B 

Left Argument Domain 

Type Variable name or undefined name 

Shape Any 



Right Argument Domain 



Type 


Any 


Shape 


Conforms to index argument K , if any 


Depth 


Any 


Result Domain 




Type 


Same as right argument 


Rank 


PPB 


Shape 


PS 


Depth 


sB 


Implicit Arguments 




None. 





Description 

The specification function («-) stores values in identifiers. The left argument 
(A ) must be a variable name or undefined. When the function is executed, the 
value of the right argument (B ) becomes associated with the name A . 

In addition to the uses described below, specification can also be used for 
strand and selective assignment statements. 

Specification functions can be included in the construction of other statements. 
For example, the following assigns the value 7 to C , 1 1 to B , and l M- to A : 

4<-3+fl-<-4+C->-7 
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For the form ALK1 «-B, axes of length 1 are dropped from B to allow B to 
conform to A IK1 . (For more details about the A \_K] «-B form of specification, 
see the VAXAPL User's Guide.) For example: 

Q+A+2 3pi6 
12 3 
4 5 6 

B<-3 1 lp7 8 9 

A[2;]+fl 

12 3 
7 8 9 

The specification function is a quiet function; it does not return a value if it is 
the leftmost function in a statement. 

A+2 

A 
2 

2 

D-^2 
2 

Note that the value returned by the specification function (when you require 
that it returns a value) is the value of the right argument, even if the left 
argument is indexed. For example: 

A+5 1 3 2 1 
U<-Ali]i-H 

A 
H H 3 2 1 

Possible Errors Generated 

Specification not subscripted (form A+-B) 

4 NOT A VALID SYSTEM IDENTIFIER 

7 SYNTAX ERROR ( MISSING LEFT ARGUMENT TO ASSIGNMENT) 

11 VALUE ERROR (NO VALUE TO ASSIGN) 

15 DOMAIN ERROR (ILLEGAL LEFT ARGUMENT TO ASSIGNMENT) 

15 DOMAIN ERROR (NOT A SYSTEM VARIABLE) 
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Subscripted specification (form AIK1+B ) 

11 VALUE ERROR {NO VALUE TO ASSIGN) 

11 VALUE ERROR {SUBSCRIPTED NAME IS UNDEFINED) 

15 DOMAIN ERROR {INVALID OBJECT IN INDEXED ASSIGNMENT) 

15 DOMAIN ERROR {NOT A SYSTEM VARIABLE) 

2 7 LIMIT ERROR {INTEGER TOO LARGE) 
36 INDEX RANK ERROR 

3 6 INDEX RANK ERROR { CANNOT INDEX A SCALAR) 
3 7 INDEX LENGTH ERROR 

3 7 INDEX LENGTH ERROR {INDEX LESS THAN INDEX ORIGIN) 

3 7 INDEX LENGTH ERROR {INDEX OUT OF RANGE) 

3 8 INDEX DOMAIN ERROR {ENCLOSED ARRAY NOT ALLOWED) 

38 INDEX DOMAIN ERROR {INCORRECT TYPE) 

3 8 INDEX DOMAIN ERROR {NOT AN INTEGER) 
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Strand Assignment with the Specification Function 



Form 




(41. . .An) «-B 




Left Argument Domain 


type 


List of variable or undefined names 


Shape 


Any 


Right Argument Domain 


Type 


Any 


Shape 


Vector domain 


Depth 


Any 


Result Domain 




Type 


Same as right argument 


Rank 


ppB 


Shape 


PB 


Depth 


= B 



Implicit Arguments 

None. 

Description 



Strand assignment (also known as vector assignment) allows you to assign a 
list of values to a list of objects. APL applies the assignment along successive 
pairs of items in the left (A ) and right (B ) arguments in a manner similar to 
scalar extension. The objects in A may be undefined names, variable names, 
or system variable names. The result of the strand assignment function is the 
right argument. 

The length of B must conform to the number of objects in A , or B must be a 
singleton, in which case APL performs singleton extension. For example: 
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32 



"12 



20 
"15 



BURR <- 32 o T£MP *■ o C0£D +- 12 
BURR o TEMP o COLD 



^PARENTHESES REQUIRED 
(BURR TEMP COLD) *■ 20 ~\ "15 
BURR o TEMP COLD 



^SINGLETON EXTENSION 

(BURR TEMP COLD) *■ 3 

flffj?/? o T£MP o COLD 
"3 
"3 
"3 

You can use strand assignment to allow multiple arguments in user-defined 
operations. For example, FRET is a monadic user-defined function containing 
three local variables (X , Y , and Z ). The header definition of FRET is as follows: 

VFRET B;X;Y;Z V 

When FRET is called, the argument (B ) contains three items. Inside FRET, 
there is an expression that performs a strand assignment in which each item 
in B is assigned to a local variable. For example: 

BIP+23 HI 'RUE' nBIP CONTAINS 3 ITEMS 

FRET BIP »TEE CALL TO FRET IS STILL MONADIC 



(I Y Z)<-BIP aTEIS IS EXPRESSION INSIDE OF FRET 

Note that the length (3) of the left argument to the specification function 
conforms to the number of items in BIP. If BIP were a singleton, APL would 
perform singleton extension. 

Strand assignment is an atomic operation; if any of the assignments fail, no 
change occurs to any of the names in the left argument list. However, If you 
have set the display option on the Q WA TCH system function (see Chapter 2 
if you have set the signal option, the signal is held until APL completes the 
entire strand assignment and only the last watched name is signaled. 
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Possible Errors Generated 

1+ NOT A VALID SYSTEM IDENTIFIER 

7 SYNTAX ERROR (MISSING LEFT ARGUMENT TO ASSIGNMENT) 

9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR 

15 DOMAIN ERROR (INVALID OBJECT IN STRAND ASSIGNMENT) 

11 VALUE ERROR (NO VALUE TO ASSIGN) 

15 DOMAIN ERROR (NOT A SYSTEM VARIABLE) 
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Selective Assignment with the Specification Function 
Form 

(fA)+B (CfA)i-B 

Left Argument Domain 



Type 



A is a variable name 

/"is a function (see list below) 

C is any valid left argument to f 



bhape 


Any 


Right Argument Domain 


Type 


Any 


Shape 


Conforms to left argument 


Depth 


Any 


Result Domain 




Type 


Same as right argument 


Rawrite nk 


ppS 


Shape 


PS 


Depth 


= B 


Implicit Arguments 




None. 




Description 





Selective assignment allows you to assign values to specified items of an 
array. The left argument (fA ) contains an expression that selects items from 
an array. The length of the right argument (S ) either equals the number of 
items selected or is 1 (B is a singleton), in which case APL performs singleton 
extension. For example: 
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12 3 4 5 

Q<- (3+GOT)«-48 49 50 aASSIGN TO FIRST 3 ITEMS OF GUT 
48 49 50 45 

D-i- OtCffD^iO aSINGLETON EXTENSION 



rSHAPES DO NOT MATCH 



48 48 48 45 

(3tff£/r)-<-48 49 
10 LENGTH ERROR 

(3 + G£/!n<-48 49 

A 

The following table describes the primitive functions you can use in the left 
argument expression to select items from an array. The symbol I refers to an 
expression that is a valid argument to the function in the form. 

Assignment Form Function Name 

( ,A)+B Ravel 

( , [id A ) +- B Ravel with axis 

( ty A ) ■*- B Reverse 

(eA) <-B 

( <)> [if] A ) +- B Reverse with axis 

( e IKHA) +■ B 

( §A) *■ B Transpose 

( I-M) *■ B Drop 

( 1+ LK1A) +• B Drop with axis 

( I* A) *■ B Take 

( 1+ [if ] 4 ) +• B Take with axis 

(I<M) *■ B Rotate 

(IeA) *■ B 

(IfyLKlA) ■*- B Rotate with axis 

( Is EK1A) ■»- B 

( 14) 4 ) +- B Transpose 

( Ipi4) +• B Reshape 

(I\A) *■ B Expand 

(I\A) *■ B 

(I\LK]A) ■+• B Expand with axis 
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Assignment Form Function Name 



(I\ IK] A) <- B 

(I/A) *■ B Replicate 

(HA) *■ B 

( 1 1 IK] A ) +• B Replicate with axis 

(1/ £K1A) *■ B 



You can use more than one of the eligible functions in the left argument 
expression. For example: 



0<-BOP-<-3 3p i 9 
1 2 3 
4 5 6 
7 8 9 

□<-(2tl lt«BOPH0 nCHANGE FIRST 2 IMMS Off ffl£ DIAGONAL 

2 3 
4 6 
7 8 9 

You can use other primitive functions in the portion of the left argument 
expression that evaluates the argument of one of the eligible functions. For 
example: 

0<-BOP-<-3 3pi9 

1 2 3 
4 5 6 
7 8 9 

BE+1 

EP<-2 

D«-((B£+£P)U 1$B0P)*-O 
2 3 
4 6 
7 8 

Possible Errors Generated 

4- NOT A VALID SYSTEM IDENTIFIER 

11 VALUE ERROR (NO VALUE TO ASSIGN) 

15 DOMAIN ERROR ( CANNOT MODIFY SELECTIVE ASSIGNMENT TARGET) 
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15 DOMAIN ERROR (INVALID FUNCTION IN SELECTIVE ASSIGNMENT) 

15 DOMAIN ERROR (INVALID OBJECT IN SELECTIVE ASSIGNMENT) 

15 DOMAIN ERROR (NOT A SYSTEM VARIABLE) 

3 6 INDEX RANK ERROR 

3 7 INDEX LENGTH ERROR 
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VAX APL System Variables and Functions 



Conceptually, there are two parts to the VAX APL interpreter: the APL 
language and the APL environment. The APL language comprises the lexical 
and symbolic elements of APL, the parts of APL that are included when it is 
used as a mathematical notation in a classroom. The APL environment is the 
setting in which the APL language elements are applied. 

The APL interpreter recognizes a set of system variables, functions, and 
commands that allow you to control your APL sessions, as well as to facilitate 
and preserve the work you do in those sessions. For example, the interpreter 
allows you to: 

• Determine or set the values of the index origin, print precision, comparison 
tolerance, and other elements that affect the operation of functions. 

• Get information about a workspace, such as its name and size, the 
names of its user-defined operations and variables, the state of its active 
operations, and so on. 

• Manipulate workspaces; that is, load, save, or delete them, copy objects 
from them, or change their size. 

• Get the system time and date, or get accounting information for a session. 

2.1 System Variables 

VAX APL system variables, like ordinary variables, can be used in any 
language expression or function. Unlike ordinary variables, system variables 
have special meaning to the system, and they allow you to do the following: 

• Set the index origin and comparison tolerance. 

• Change the output precision and line width. 

• Specify an operation to be performed when a workspace is activated. 

• Automatically save an active workspace after function editing and data 
input. 
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2.1.1 System Variable Names 

The names of APL system variables begin with a quad character (D ). The 
names are considered to be distinguished names, meaning that they are 
reserved for a specific purpose. You cannot use them as names for user-defined 
operations or variables, and you cannot copy, erase, or collect them in a group. 

2.1 .2 System Variable Characteristics 

System variables are similar to ordinary variables in the following ways: 

• They retain their values until new ones are assigned. 

• Their current values are saved with a workspace (except for D GAG, Q TT, 
□ TLE and □ VPC). 

• They can be localized in user-defined operation definitions. 

Each of the system variables in APL can be assigned a value and can be 
localized in user-defined operations. 

Table 2-1 lists the system variables, the range of values you can specify for 
them, and their default values. 

Table 2-1 System Variable Value Ranges 



Variable 



Value Range 



Default 



DAUS 


0, 1,2 





QCT 


to 2.328E" 10 


IE" 15 


UDC 


Nested vector 


("" 1 1 2) ' ' 


UDML 


512 to 2048 


2048 


D ERROR 


Error message 


i t 


UGAG 


0, 1, 2, 3 


Terminal dependent 


uio 


0,1 


1 


DL 


Any 


i0 


OLX 


Expression 


t 1 


QNG 


0,1,2 


1 


DPP 


ltol6 


10 


DPW 


35 to 2044 


Terminal width 


DR 


Any 


i0 



(continued on next page) 
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Table 2-1 (Cont.) System Variable Value Ranges 



Variable 



Value Range 



Default 



URL 


~ 2147483648 to 
2147483647 


695197565 


USF 


Prompt 


□ :<CRxLF> 6 spaces 


USINK 


Any 


Always i 


D TERSE 


0, 1 





TIME LIMIT 


" 1 to 255 





TIMEOUT 


0,1 





UTLE 


0, 1 


Terminal dependent 


UTRAP 


Expression 


i t 


UTT 


ltol9 


Terminal dependent 


QVPC 


Non-negative integer 


30 



Note that 0ERR0R, QLX, USF, and UTRAP must have character values; UDC 
has a two-item heterogeneous value; all the other system variables must have 
numeric values. The exceptions are DL,DR, and USINK, which may take any 
type of value. 

2.2 System Functions 

APL system functions supplement the primitive functions by providing 
additional processing capabilities. For instance, they allow you to do the 
following: 

• Express the canonical representation of a user-defined operation and store 
the operation definition as data. 

• Expunge a named object. 

• Construct a name list of labels, variables, or functions, and return the 
classification of a named object. 

• Delay execution of an operation for a specified period of time. 

You access a system function by stating its name and arguments (if any), just 
as you would access a primitive or user-defined operation. 

For the system functions that take character arguments, white space (spaces 
and tabs) is allowed before and after the name (workspace name, function 
name, and so on) in the argument. For example, all of the following will load 

the workspace MYWS: 
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UQLD ' MYUS ' 

UQLD ' MYUS ' 

UQLD <MWS' 

QQLD ' MYUS ' 

Anything other than white space is not allowed before or after the name: 

QQLD ' MYUS 4< 

22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 
UQLD ' MYUS A' 

A 

2.2.1 System Function Names 

System functions, like system variables, are identified by unique names that 
begin with a quad character (D ); you cannot use these names for user-defined 
operations or variables, and you cannot copy, erase, or collect them in a group. 
APL assumes that any system functions in an expression are ambivalent, 
even though most system functions have a specific valence. This means that 
if an expression contains a left argument for a monadic system function, APL 
signals an error. For example: 

nQARBOUT IS MONADIC 
2 QARBOUT 3 
7 SYNTAX ERROR (NO DYADIC FORM OF FUNCTION) 
2 UARBOUT 3 

A 

2.2.2 Types of System Functions 

System functions can be categorized as follows: 

• Mladic system functions — those that do not take arguments. 

• Monadic system functions — those that take one argument. 

• Dyadic system functions — those that take two arguments. 

• Ambivalent system functions — those that take either one or two arguments. 

The niladic system functions do not take arguments (you may not assign 
a value to them), and they cannot be localized in user-defined operations. 
The niladic system functions and their values (where applicable) in a clear 
workspace may be summarized as follows: 
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Function 



Niladic System Functions 
Description (value in clear workspace) 



QAI Account information as 4-integer vector 

UALPHA ' AABCDEFGHIJKLMNOPQRSTUVWXYZ' 

OALPHAL ' abcdelgh i j klmnop q c s tuvwxyz ' 

UALPHAU ' &ABCDEFGHIJKLMN OPQRSTUVWXYZ ' 

ASCI I QAV subset; approximates ASCII characters 

D A V Atomic vector 

□ CHANS Assigned file channels (empty numeric vector) 
CTRL The first 32 ASCII characters and Delete 
QIC Line numbers in state indicator (i o) 

QNUM ' 0123^56789 ' 

D RESET Clears the state indicator (no value) 

TS Time stamp as 7-integer vector 

□ UL Process identification number (PID) 
D VERSION Interpreter and workspace versions 

□ WA Workspace available in bytes 

The monadic system functions take one argument, which is placed immediately 
to the right of the function. The following table of the monadic system 
functions describes the type, shape, and, where applicable, the units associated 
with each function's argument. Note that there are two entries for QASS, 
which has both action and query uses. 





Monadic System 


Functions 


Function 


Shape 


Type 


Units 


UARBOUT 


Vector domain 


Integer 


Character codes 


QASS 


Vector domain 


Character 


File information 


UASS 


Vector domain 


Near-int 


Channel numbers 


D BREAK 


Any 


Any 


N/A 


OCHS 


Vector domain 


Near-int 


Channel numbers 


UCLS 


Vector domain 


Near-int 


Channel numbers 


DCR 


Vector domain 


Character 


Operation name 


QDAS 


Vector domain 


Near-int 


Channel numbers 
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Monadic System 


Functions 


Function 


Shape 


Type 


Units 


DDL 


Singleton 


Floating 


Seconds 


DDVC 


Vector domain 


Near-int 


Channel numbers 


UEFC 


Vector domain 


Near-int 


Channel numbers 


QEFR 


Vector domain 


Near-int 


Channel numbers 


DEFS 


Vector domain 


Near-int 


Channel numbers 


UEX 


Matrix domain 


Character 


Name list 


UFI 


Vector domain 


Character 


Numeric string 


QFLS 


Vector domain 


Near-int 


Channel numbers 


UFX 


Matrix domain 


Character 


Operation definition 


UMBX 


Vector domain 


Near-int 


Channel numbers 


DNC 


Matrix domain 


Character 


Name list 


UOM 


Vector domain 


Near-Bool 


N/A 


UQCO 


Vector domain 


Character 


Workspace name, object names 


DQLD 


Vector domain 


Character 


Workspace name 


QQPC 


Vector domain 


Character 


Workspace name, object names 


□ RELEASE 


Vector domain 


Near-int 


Channel numbers 


QVI 


Vector domain 


Character 


Numeric string 


QVR 


Vector domain 


Any 


Value or object name 


UXQ 


Vector domain 


Any 


N/A 



The dyadic system functions take both a left and a right argument. The dyadic 
system functions and the type, shape, and units, if any, associated with their 
arguments are as follows. 







Dyadic System Functions 


Function 




Shape 


Type 


Units 


OCIQ 


Left: 


Vector domain 


Near-int 


Packed data 




Right: 


Vector domain 


Near-int 


Control information 


UCOQ 


Left: 


Array 


Any 


Data to be packed 




Right: 


Vector domain 


Near-int 


Control information 


DEXP 


Left: 


Vector domain 


Near-Bool 


Expand information 
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Dyadic 


System Functions 


Function 




Shape 


Type 


Units 




Right: 


Any 


Any 


Array to be expanded 


OFMT 


Left: 


Vector domain 


Character 


Format string 




Right: 


Any 


Any 


Data to be formatted 


OREP 


Left: 


Vector domain 


Near-int 


Replicate information 




Right: 


Any 


Any 


Array to be replicated 


OSS 


Left: 


Vector domain 


Character 


Pattern string 




Right: 


Vector domain 


Character 


String 



The ambivalent system functions may be monadic or dyadic; thus, they take 
either a right argument only, or they take both a right and a left argument. 
The following table of the ambivalent system functions describes the type, 
shape, and, where applicable, the units associated with each function's 
arguments: 







Ambivalent System Functions 




Function 




Shape 


Type 


Units 


UBOX 


Left: 


Vector domain 


Character 


Delimiter 




Right: 


Matrix domain 


Character 


Delimited lines 


UMAP 


Left: 


Vector domain 


Character 


Function header 




Right: 


Vector domain 


Character 


Shared image def/function 
name 


MONITOR 


Left: 


Vector domain 


Numeric 


Line numbers 




Right: 


Matrix domain 


Character 


Operation names 


UNL 


Left: 


Vector domain 


Character 


Letter list 




Right: 


Vector domain 


Near-int 


Name classes 


DPACK 


Left: 


Vector domain 


Numeric 


Data packets 




Right: 


Matrix domain 


Character 


Variable names 


□ REWIND 


Left: 


Singleton 


Near-int 


Key of reference 




Right: 


Vector domain 


Near-int 


Channel numbers 


□ SIGNAL 


Left: 


Vector domain 


Character 


Error message 




Right: 


Singleton 


Near-int 


Error number 


nsfop 


Left: 


Vector domain 


Near-int 


Line numbers 
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Ambivalent 


System Functions 




Function 




Shape 


Type 


Units 




Right: 


Matrix domain 


Character 


Operation names 


D TRA CE 


Left: 


Vector domain 


Near-int 


Line numbers 




Right: 


Matrix domain 


Character 


Operation names 


UWAIT 


Left: 


Singleton 


Near-int 


Time limit 




Right: 


Vector domain 


Near-int 


Channel numbers 


D WATCH 


Left: 


Singleton 


Near-int 


Watch mode 




Right: 


Matrix domain 


Character 


Variable names 



Another type of system function is the quiet function, a category that is 
independent of the valence of the function. Quiet functions do not generally 
cause APL to display a value when they are evaluated as the leftmost function 
in a statement. The following table shows the quiet functions: 





Quiet System Functions 


Monadic 


Dyadic Ambivalent 


OARBOUT 


a 


-* (always) 


UWAIT U REWIND 


ncLs 


DXQ (sometimes) 


DDAS 


4 (sometimes) 


UQCO 




UQLD 




DQPC 




U RELEASE 





However, a quiet function displays a value if you enclose the function and its 
arguments in parentheses (note that the branch function (-*- ) is always quiet). 
The OXQ and t functions are quiet when the argument is quiet; otherwise DXQ 
and * cause APL to display a value. For example: 
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4+5 ^SPECIFICATION FUNCTION IS QUIET. NO DISPLAY 

(4+5) «ADD PARENTHESIS IF YOU WANT A DISPLAY 
5 

{B+'THIS MILL PRINT BECAUSE OF THE PARENTHESES') 
THIS WILL PRINT BECAUSE OF THE PARENTHESES 

QXQ '4+10' rUXQ ARGUMENT IS NOT QUIET 
15 

DIG '04+10' AQXfi ARGUMENT IS QUIET. NO DISPLAY 

2.3 System Variables and Functions Reference 

The following sections describe the APL system variables and functions in 
alphabetical order. Table 2-2 lists the system variables and functions and 
gives a brief description of their uses. APL displays an alphabetical list of 
these variables and functions when you enter the following expression: 

X*-DNL "2"3"5oI[^;] 

Table 2-2 System Variables and Functions 



Name 



Meaning 



UAI Maintains account information on the current APL session. Includes 

user identification, CPU time, and connect time. 

D ALPHA Vector of 27 characters: A and A through Z. 

UALPHAL Vector of 26 lowercase characters: a through z. 

□ ALPHA U Vector of 27 underscored characters. 
UARBOUT Writes arbitrary output to the terminal. 

UASCII Subset of UAV approximates the ASCII character set. 

BASS Associates a file or mailbox with a channel. 

UAUS Specifies periodic workspace backup. 

□ A V Vector of all APL characters. 

BOX Returns a matrix from a character vector and vice versa. (The rows 

of the matrix are delimited by a specified string.) 

D BREAK Suspends operation execution and returns control to immediate 

mode. 

D CHANS Identifies channel numbers associated with files. 

□ CHS Returns file organization and open status on one or more channels. 
D CIQ Unpacks data packed by □ COQ. 

(continued on next page) 
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Table 2-2 (Cont.) System Variables and Functions 



Name 



Meaning 



UCLS 

ucoq 
ucr 

DCT 

UCTRL 

DDAS 

QDC 

DDL 

DDML 

UDVC 

UEFC 

DEFR 

UEFS 

D ERROR 

DEX 

UEXP 

UFI 

DFLS 

UFMT 

UFX 

UGAG 

UIO 

UL 

DLC 



Closes the files on one or more channels. 

Packs data of different types for storage as one record. 

Returns a canonical representation of a user-defined operation 
whose name is the character string specified. 

Determines the degree of tolerance applied in numeric comparisons. 

Vector of ASCII control characters. 

Disassociates files from one or more channels. 

Controls the display of enclosed arrays. 

Delays execution by the number of seconds specified. 

Controls default maximum record length used to save the workspace 
or to create a file. 

Returns the device characteristics longword for one or more 
channels. 

Clears event flags associated with one or more channels. 

Returns the setting for event flags on one or more channels. 

Sets event flags associated with one or more channels. 

Character vector that describes last error to occur. 

Expunges existing use of a name in the workspace. 

Expands an array by adding fill items in the same manner as the 
expansion derived function. 

Converts character argument to numeric, placing Os in each position 
not corresponding to a valid number. 

Returns information about files on one or more channels. 

Converts argument to character matrix in designated format. 

Establishes an operation from its canonical representation. 

Indicates whether to accept broadcast messages. 

Sets index origin for arrays; must be or 1. 

Contains the name of a changed variable that is being watched by 

WATCH. 

Vector of line numbers in state indicator; most recently suspended 
operation appears first. 

(continued on next page) 
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Table 2-2 (Cont.) System Variables and Functions 



Name 



Meaning 



ULX Contains an expression to be executed automatically when 

workspace is loaded. 

UMAP Associates an external routine with a user-defined function. 

QMBX Returns information about mailboxes on one or more channels. 

□ MONITOR Gathers information about operation execution counts and CPU 

times. 

QNC Returns the classification of one or more names. 

ONG Controls recognition and printing of negative sign. 

ONL Constructs a list of named objects residing in the active workspace. 

ONUM Vector of 10 numeric characters: through 9. 

D 0M Returns the index of every occurrence of a 1 in a Boolean vector. 

□ PA CK Packs and unpacks data for storage as one record. 

□ PP Controls precision of noninteger numeric output. 

□ PW Sets maximum number of characters in output line. 
UQCO Quietly copies a workspace. 

OQLD Quietly loads a workspace. 

UQPC Quietly copies a workspace with certain protection. 

OR Contains the previous value of a changed variable that is being 

watched by WA TCH. 

ORELEASE Releases all locked records in files on one or more channels. 

QREP Compresses or replicates an array in the same manner as the 

compression and replication derived functions. 

ORE SET Clears the state indicator. 

REWIND Repositions the next record pointer to the first record of a file on one 

or more channels. 

□ RL Forms link in chain of random numbers used in roll and deal 

functions. 

D SF Prompt for evaluated input. 

SIGNAL Passes an error up the stack one level to the caller of the operation 

in error. 

D SINK Discards unwanted output; always i o . 

(continued on next page) 



APL Reference Manual 2-11 



VAX APL System Variables and Functions 
2.3 System Variables and Functions Reference 



Table 2-2 (Cont.) System Variables and Functions 



Name 



Meaning 



□ SS Searches the right argument for every occurrence of a character 

string specified in the left argument. 

QSTOP Sets or clears stop bits associated with operation lines. 

□ TERSE Suppresses display of secondary error messages. 

□ TIMELIMIT Limits time to respond to quote quad and quad del input requests. 

□ TIMEOUT Equals 1 if time runs out during quote quad or quad del input 

request; otherwise, equals 0. 

D TLE Equals 1 when the terminal line editing attribute is on and when 

line editing is off. 

□ TRACE Sets or clears trace bits associated with operation lines. 

D TRAP Contains an expression to be executed when an error occurs. 

D TS Current date and time in base 10 format. 

UTT Determines the type of terminal being used for the current APL 

session. 

D UL Process identification number. 

VERSION Interpreter and workspace versions. 

D VI Returns logical vector giving position of valid numbers in □ FI of 

argument. 

D VPC Controls the use of vector processing hardware. 

□ VR Returns a visual representation of a value or user-defined operation 

whose name is the argument specified. 

□ WA Maximum amount in bytes by which the active workspace can be 

increased. 

□ WAIT Determines how long a read function waits for control of a shared 

record. 

□ WATCH Watches changes or references to the values of variables. 
D XQ Executes character strings with error handling. 
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UAI Accounting Information 
Type 



Niladic System 


Function 


Form 




uic 1 cpu-time / connect-time *■ UAI 


Result Domain 




Type 


Integer 


Rank 


l (vector) 


Shape 


4 


Depth 


l (simple) 


Description 





DAI returns a vector of the user identification number (uic), computer time 
(cpu-time) used during the current APL session, and time elapsed (connect- 
time) since the beginning of the current APL session. 

For the user identification code GROUP, MEMBER, the uic is 

MEMBER+ ( GROUP* 2 * 16 ) . All times are expressed in milliseconds. The fourth 
element is always o . For example: 

589825 390 1190 

VMS expresses the GROUP and MEMBER numbers in QAI [1] in octal. The 
following APL expression returns those numbers: 

10i8 8 8t(0,2*16)t[MI[1] 
11 1 

Possible Errors Generated 

None. 
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D ALPHA Alphabetic Characters 
Type 



Mladic System 


Function 


Form 

• AABCDEFGHIJKLMNOPQRSTUVWXYZ 


Result Domain 




Type 


Character 


Rank 


l (vector) 


Shape 


27 


Depth 


l (simple) 


Description 





QALPHA 



U ALPHA is a subset of OAV; it returns a vector of the 27 alphabetic characters 
that may be used in identifiers. They are A and A through Z , or, expressed in 
terms of D A V: 

UAVKUIO+72), 97+i26] 
For example: 

UALPHA 
bABCDEFGHIJKLMNOPQRSTUVHXYZ 
UIO+O o QPU<-52 
UAV i UALPHA 

72 97 98 99 100 101 102 103 lOt 105 106 107 108 109 
110 111 112 113 lit 115 116 117 118 119 120 
121 122 

Possible Errors Generated 

None. 
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UAL PHA L Lowercase Alphabetics 
Type 

Niladic System Function 

Form 

' abcdefgliijklmnopqrstuvwxyz' ■*- Q ALPHAL 

Result Domain 



Type 


Character 


Rank 


l (vector) 


Shape 


26 


Depth 


l (simple) 


Description 





D ALPHAL is a subset of UAV; it returns a vector of the 26 lowercase alphabetic 
characters. They are a through z , or, expressed in terms of Q A V: 

DA7[129+i26] 
For example: 

UALPHAL 
abcdefghijklmnopqrstuvvxyz 

QIO-H) o 0Ptf<-52 

UAV i QALPHAL 
129 130 131 132 133 13M- 135 136 137 138 139 HO 141 

142 143 144 145 146 147 148 149 150 151 152 

153 154 

Possible Errors Generated 

None. 
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D ALPHA U Underscored Alphabetics 
Type 

Niladic System Function 

Form 

' LABCDEFGHIJKLMNOPQRST UVWXYZ' *■ UALPHAU 

Result Domain 



Type 


Character 


Rank 


l (vector) 


Shape 


27 


Depth 


l (simple) 


Description 





DALPHAU is a subset of QAV; it returns a vector of the 27 underscored 
alphabetic characters that may be used in identifiers. They are A and A 
through Z , or, expressed in terms of D A V: 

Q4V[160+i27] 
For example: 

QALPHAU 
LAiCDEFGBIJKLMIlOPQRSTUVHXYZ 

QIO-K) o DPW+-52 

QAV i UALPHAU 
160 161 162 163 164 165 166 167 168 169 170 171 172 

173 174 175 176 177 178 179 180 181 182 183 

184 185 186 

Possible Errors Generated 

None. 
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D ARBOUT Arbitrary Output 
Type 



Form 



Monadic System Function (quiet) 



i0 +- UARBOUT 



Argument Domain 



TVpe 


Near-integer 


Shape 


Vector domain 


Depth 


l (simple) 


Value 


o through 255 



Result Domain 



TVpe 


Numeric 


Rank 


1 (vector) 


Shape 


(empty) 


Depth 


l (simple) 


Description 





UARBOUT allows you to send untranslated output to the terminal (actually, to 
the default output device). Q ARBOUT outputs the argument's items as if they 
were character codes. 

One use of UARBOUT is to write a file of ASCII characters, where each of the 
integers corresponds to a character in the ASCII character set. You cannot 
use the file system function B (see the VAX APL User's Guide) with UARBOUT 
to write the file because UARBOUT sends output only to your default output 
device, usually your terminal. You can use the ) OUTPUT system command (see 
the VAX APL User's Guide), however, to divert output from your terminal to a 
file. For example: 
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) OUTPUT ASCFILE 

QARBOUT 35 37 38 42 64 94 95 

) OUTPUT 

aCHANGE TO ASCII CHARACTER SET 

)PUSH 
$TYPE ASCFILE. MS 

QARBOUT 35 37 38 42 64 
#%U@ )0UTPUT 

$ 

APL does not append a <CRxLF> to OARBOUT output. 

If you use OARBOUT immediately following or output, QARBOUT resets the 
bare output buffer. For details, see the VAX APL User's Guide. 

QARBOUT is a quiet function; that is, it does not return a result if it is the 
leftmost function in a statement. If it is not the leftmost function, QARBOUT 
returns i as its result. 

Possible Errors Generated 

9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 

15 DOMAIN ERROR 
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□ ASCII APL Approximation to the ASCII Character Set 
Type 



Niladic system 


function 


Form 




ASCII-characters *■ DAS CI I 


Result Domain 




T>pe 


Character 


Rank 


l (vector) 


Shape 


128 


Depth 


l (simple) 



Description 

D AS CI I is a subset of DA V; it returns a vector of 128 characters that 
approximates the 7-bit ASCII character set. D ASCI I contains the ASCII 
control characters (D CTRL) and the lowercase letters (QALPHAL). For example: 



(32+QASCII) e 32 + QCm 
CliUASCII) = 'UUCTRL 
Q4SCII[33] = ' ' fi33M> ITEM IS AN EMPTY SPACE 



uDISPLAY ALL BUT THE CTRL CHARACTERS 
2 47 p 94+33+D4SCII 
! "#$%& '()*+,-. /0123456789 :;<=> ?@ABCDEFGHIJKLMWO 
PQRSTUVWXYZl\lA_'abcdefghijklmnopqrstuvvxyz{\}~ 

Possible Errors Generated 

None. 



APL Reference Manual 2-19 



System Variables and Functions 

BASS Associating Files with Channels 



□ ASS Associating Files with Channels 
Type 

Monadic System Function (action form) 

Form 

variable *■ UASS ' Ichannell filespec l/fileorganizationJ< 

Argument Domain 





Type 


Character 




Shape 


Vector domain 




Depth 


l (simple) 


Result Domain 






Rank 


(scalar) 




Shape 


i (scalar) 




Depth 


(simple scalar) 


Type 








Monadic System 


i Function (query form) 


Form 








current-assignments ■*• UASS channel 


Argun 


lent Domain 






Type 


Near-Integer 




Shape 


Vector domain 




Depth 


(simple scalar) 




Value 


~ 9 9 9 through 9 9 9 (but not ) 
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Result Domain 



Type 


Character 


Rank 


1 or 2 


Shape 


Vector or matrix 


Depth 


l (simple) 



Parameters 



variable 

Is an optional variable used when writing to or reading from this file and 
channel combination. 

channel 

Is an optional integer scalar whose absolute value represents a channel 
number in the range 1 through 999. If you do not specify a channel number, 
APL assigns one for you. APL picks the first available channel number, 
beginning at 12 and counting down to 1; then APL begins at 13 and counts up 
to 999. 

filespec 

Is the VMS file specification associated with the specified channel. If you do 
not include the file extension, APL uses the default file extension for the file 
organization qualifier specified. (See Table 2-3.) 

/fileorganization 

Identifies the file organization of the file specified by filespec. The possible 
values of /fileorganization are listed in Table 2-3. The default value is /DA. 

Table 2-3 File Organization Qualifiers 

/fileorganization Default File 

Qualifier Extension Type of File 

/AS .AAS ASCII sequential; can open for either 

read or write, or both (when you specify 

/UPDATE). 

/AS* .AAS ASCII sequential; file is positioned at 

end-of-file to allow appending. 

(continued on next page) 
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Table 2-3 (Cont.) File Organization Qualifiers 



/fileorganization Default File 

Qualifier Extension Type of File 



/IS .AIS Internal sequential; can open for either 

read or write, or both (when you specify 

/UPDATE). 

/IS* .AIS Internal sequential; file is positioned at 

end-of-file to allow appending. 

/DA -AIX Direct-access; can do read and write (this is 

the default). 

/RF .ARF Relative; can do read and write. 

/KJ . AKY Keyed; can do read and write. 



current-assignments 

A vector containing the current value of assignments. 



Qualifiers 



/blocks I ze liblocksizej 

For input on nondisk devices, it specifies the minimum size memory buffer 
for APL to make available. The default is 2044 bytes or the current /MAXLEN 
value, whichever is smaller. 

In all other cases, it is ignored. In addition, it is always ignored for ASCII 
sequential files (the blocksize is always 2044 bytes.) 

/BUFFERCOUNT [:flj 

Specifies how many I/O buffers you want allocated to read and write to a file. 
The acceptable values for n is through 127. The default is 0, which means 
that the number of allocated buffers will be the same as the current system 
default value. 

/c control I: keyword^ 

Specifies the carriage control attribute for a new, sequential file. (The qualifier 
is ignored for nonsequential file organizations.) When you do not specify 
/CCONTROL, or when you do not specify a keyword, the carriage controls are set 
according to the file type. 
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Valid keywords include the following: 



Keyword 



Carriage control Attribute 



Default 



FORTRAN The first character of each record 

will contain the appropriate carriage 
control information 

LIST Implied carriage control (single 

spacing between records) 

NONE No carriage control information (any 

carriage control information will be 
placed in individual records) 



Default for I AS files. 



Default for /IS files. 



/defaultfile -.defaultspec 

Specifies a default to be applied to any missing components of the filespec. The 
defaultspec must be specified. APL first looks at the file specification named 
in the argument. If any components are missing, APL looks for a default in 
the /DEFAULTFILE qualifier. If you omit the defaultspec, APL specifies the 
appropriate APL file type. 

/DISPOSE l:keyword$ 

Specifies whether the file is temporary or permanent. /DISPOSE -.KEEP, the 
default, means the file is permanent. /DISPOSE -.DELETE means the file will be 
deleted when it is closed. 

Other keywords send the file to a queue when the file is closed in accordance 
with the following: 



Keyword 



Definition 



PRINT Sends the file to SYS$PRINT. The file is not deleted. 

PRINTDELETE Sends the file to SYS$PRINT. The file is deleted when job is 
finished. 

SUBMIT Sends the file to SYS$BATCH. The file is not deleted. 

SUBMITDELETE Sends the file to SYS$BATCH The file is deleted when job is 
finished. 

Note that you must have VMS delete privileges to use any of the delete 
keywords. If you do not have delete privileges, APL signals FILE PROTECTION 
VIOLATION when the file closes. As a result, APL closes the file, but does 
not delete it. If you receive the file protection violation error when you press 
Ctrl/Z, you can exit from APL by pressing Ctrl/Z a second time. 
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/efn :n 

Associates an event flag with a channel number. For more information on 

event flags see QEFR,DEFS, and QEFC. 

/maxlen [: length® 

Specifies the maximum record length (in bytes) for a new file. It is ignored for 
existing files. The default length is the value of the D DHL system variable. The 
maximum record length value is also used as the maximum segment size for 
segmented records on output. 

The maximum values are as follows: 

• 32232 (for prolog 1 or 2) 

• 32224 for / DA and / KY files (prolog 3) 

• 32767 for / IS files 

• 2048 for / AS files 

• 32253 for / RF files 

When you write to an /AS file in quad output mode, the maximum record 
length is determined by the current setting of D PW. In all other output modes 
for all file types, the maximum record length is determined by /MAXLEN. 

/MBX 

Indicates that an assigned file name actually refers to a mailbox. 

/NFS 

A non-file-structured qualifier that tells APL to read from the device without 
trying to interpret the data. In other words, to return the data on the device 
as a string of bits. This qualifier is useful when reading foreign devices. 

/NO SHARE 

/NOWRITERS 

Allows you to write to a shareable file, but prevents other users from doing so. 

/open fckeyword$ 

Specifies that you want APL to open or create a file when the channel is 
assigned. Using the /OPEN qualifier allows you to detect errors related to the 
openning or creating of a file at the time of assignment instead of at the time 
of the first I/O operation. Values for keyword include NEW, used to create a new 
file, and OLD, used to open an existing file. 
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/protection l.protectionj 

Specifies the protection to be associated with a new file. It is ignored for 

existing files. 

/READONLY fiNOLOCKSj 

Allows you to read the file but not write to it. The NO LOCKS argument specifies 
that records should be read even if they have been locked by another user. 
Using / READONLY : NO LOCKS avoids waiting for a locked record to become 
unlocked. However, note that when QWAIT is set to any value but the default 
(wait indefinitely), it overrides the NOLOCKS argument. 

/recordtype fckeywordft 

Specifies the record format used by VAX RMS for each record of the file. The 
default is variable length records. APL ignores this qualifier if the file already 
exists or if the file type is /DA, /RF, or /KY. You can use the following keywords 
as values to /RECORDTYPE. 

Keyword Record Format 

VARIABLE Variable length 

FIXED Fixed length 

STREAM Stream format 

STREAMCR Stream format delimited with <CR>s 

STREAMLF Stream format delimited with <LF>s 

Note that when you use fixed-length records, the record size is defined with the 
/MAXLEN qualifier. The default value is DDML. 

Because APL adds a prefix containing system information to each record of 
a /IS file, you may want to write data out to these files in pure data mode 
when using fixed-length records. Otherwise you need to calculate the size of 
the prefixed information before writing the data. 

/SHARE 

Specifies that several users may access the file simultaneously. All users 
sharing the file must use the /SHARE qualifier when associating a given file 
with a channel. Sequential file users are exempted from this rule. 

/SIGNAL 

Specifies that APL signal the end-of-file indicator when you perform a read 
operation on a nonexistent record. For /AS and /IS files the indicator is EOF 
ENCOUNTERED. For /DA, /RF, and /KY files the indicator is EOF ENCOUNTERED 
for a sequential read and RECORD NOT FOUND for a random read. If you do not 
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specify /SIGNAL, APL returns an empty numeric matrix with the shape of 75 
as the end-of-file indicator. 

/UPDATE 

Specifies that you want both read and write access to a sequential file and that 
APL should change the rules slightly for sharing the file. /UPDATE is relevant 
for /AS and /IS files only and is ignored for all other file types. 

When you use / UPDA TE you should consider how you want APL to deal with 
locked records. See / READONLY : NOLOCKS and QRELEASE for more information. 

/WRITEONLY 

Allows you to write to a file, but not read it. A new file is created when APL 
writes to the file. If the assignment specifies /OPEN -.OLD, a new file is not 
created. However, APL can write to an existing file only if the file is empty, or 
if / IS* was specified for appending. Subsequent assignments can gain read 
access to the file. 

Description 

The action form of Q ASS associates files with channels. QASS does not create 
or open a file (unless you use the /OPEN qualifier) or perform any input or 
output. It establishes a connection between a file specification (and related file 
information) and a specified channel. 

When you perform I/O functions, you must refer to channel numbers rather 
than to file specifications. The APL functions that perform file I/O (B and ) 
require channel numbers — not file specifications — as part of their arguments. 
So, to read or write a file, you must first associate it with a channel. 

The query form of D ASS returns the current value of assignments made 
previously with the action form. 

The result of the query form is a character vector or matrix that identifies the 
parameters you associated with the channels specified. 

Note that the action and query forms of ASS are described in in the VAX APL 
User's Guide, along with other file I/O information. 
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Possible Errors Generated 

Action Form 

15 DOMAIN ERROR (ERROR PARSING ARGUMENT TO CCONTROL) 

15 DOMAIN ERROR {REDUNDANT KEYWORD OR QUALIFIER) 

15 DOMAIN ERROR (CONFLICTING QUALIFIERS SPECIFIED) 

3 3 10 ERROR (INVALID RECORD SIZE) 

3 3 10 ERROR (FILE CURRENTLY LOCKED BY ANOTHER USER) 

68 END OF FILE ENCOUNTERED 

6 9 RECORD NOT FOUND 

7k BLOCK TOO BIG 
Query Form 

9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INVALID CHANNEL NUMBER) 

15 DOMAIN ERROR (NOT AN INTEGER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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D A US Automatic Save of the Workspace 
Type 

System Variable 

Form 

UAUS ■*- near-integer-singleton 
integer-scalar *• UAUS 



Value Domain 




TVpe 


Near-Integer 


Shape 


Singleton 


Depth 


or l (simple) 


Value 


, l , or 2 


Default 






Result Domain 



T^e 


Integer 


Rank 


o #(scalar) 


Shape 


i (scalar) 


Depth 


o #(simple scalar) 


Description 





D A US controls a feature that allows you to save the active workspace 
automatically at periodic intervals. 

Workspace backup is often critical when you are performing extensive 
operation editing and debugging, or when you are using quad input to type a 
large table of values. You could back up your work by periodically issuing a 
) SA VE command. However, if you set Q A US to 1 or 2, APL automatically saves 
the workspace every time you exit from function-definition mode, or every time 
quad input is requested from the terminal. Then, if the system crashes, you 
probably will have to reenter only a small amount of input. In addition, when 
UAUS is set to 2, the ) OFF command acts like the ) CONTINUE command (see 
Chapter 3). 
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You can set QAUS to 0, 1, or 2; the default is 0. When DA US equals 0, the 
automatic save feature is not activated. When QAUS equals 1 or 2, the feature 
is activated and the workspace is saved in your default directory as follows: 

Value of uaus File Name of Saved Workspace 

1 APLxxxxxxxx . TMP, where xxxxxxxx is the value ofQUL, 
represented in hexadecimal. (Note that Q UL is an integer 
that represents your process identification number.) 

2 CONTINUE. APL 

The name of the file saved when □ A US is 1 can be represented as the following 
APL expression: 

'APL' ,{'012ZM(,7B9ABCDEF'LQIO+(S()16)tUUL1),< .TMP' 

The value of D A US is saved when you save the active workspace and can be 
localized in user-defined operations. 

When QAUS is 2, APL keeps all versions of CONTINUE .APL, even after the APL 
session ends. 

When QAUS is 1, APL deletes all old versions of APLxxxxxxxx. TMP each time 
a new version is created during the same APL session. When you successfully 
execute a )SAVE, )0FF, or ) CONTINUE system command, APL deletes all 
APLxxxxxxxx . TMP files created during the session, including the one most 
recently created. Note, however, that APL does not delete APLxxxxxxxx . TMP 
files created in past APL sessions, unless such an APLxxxxxxxx .TMP file 
has exactly the same name as a newly created APLxxxxxxxx . TMP file. For 
example: 

UAUS+l 
UUL 
88 

, 0123i+567894BCM , F'[QI0+(8pl6)T[]{/Z] 

VC 
[1] '1' 
[2] V 

aAPL URITES .TMP FILE 

)LIB *.TMP 

Directory APLGRP-.IUSER1 
APLOOOOOOSS.TMP-,1 
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Total of 1 tile. 



aSTART new apl session with new qul 

QAUS+1 

QUL 
92 

, 0123456789ilBCMF , [DZO+(8pl6)TD(/I] 
00000051) 

VG 
[1] '1' 
[2] V 

fiAPL WRITES .TMP FILE 

)LIB *.TMP 

Directory APLGRP: LUSER1 

APL00000058.TMP-1 
APL0000005D.TMP;! 

Total of 2 files. 

)SAVE ABC 
SAVED THURSDAY 15-ffOF-1990 11:33:21.32 6 BLKS 

)LIB *.TMP 

Directory APLGRP: IUSER1 

APL0000QQ5S.TMP;1 

Total of 1 file. 

ftAPL DELETED NEW .TMP FILE BUT NOT .TMP 
h FILE CREATED IN EARLIER SESSION 

Note 



D UL has a value that changes each time you log in to VMS, and the 
names of the APLxxxxxxxx . TMP files are probably different if they are 
created during different VMS sessions. The names are the same if the 
files are created during the same VMS session, even if they are not 
created in the same APL session. 



To recover the UA US file after a system crash, execute APL and issue a.) LIB 
command to verify that the temporary file exists. Then use ) LOAD to load 
the temporary file. APL prints the )LOAD message. The name of the active 
workspace is now the name that the workspace had before the backup was 
performed, not the name of the temporary file: 



2-30 APL Reference Manual 



System Variables and Functions 

□ A US Automatic Save of the Workspace 



)LIB *.TMP 
Directory APLGRP:IUSER1 
APLOOOO0ObC.TMP;l 

Total of 1 file. 

)L0AD APL0000005C.TMP 
SAVED THURSDAY 15-H0Y-1B90 12:30:05. OH 53 BLKS* WAS ABC 

)USID 
ABC 

Possible Errors Generated 

9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (NOT SINGLETON) 
15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (NOT AN INTEGER) 

15 DOMAIN ERROR (PARAMETER OUT OF RANGE) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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D A V Atomic Vector 
Type 

Niladic System Function 

Form 

all-known-chars «- OAV 

Result Domain 



Type 


Character 


Rank 


l (vector) 


Shape 


256 


Depth 


l (simple) 


Description 





A V contains a vector of the 256 characters known to APL. Table 2-4 shows 
the characters and their positions in the vector. The positions are based on an 
index origin of 0. The index of a character is the sum of its row and column 
numbers. 

Symbols with indexes 213 through 255 have no meaning to the APL user. They 
are used only by the APL implementation and may not be used for input. On 
output, they print as squish quads (0 ). If you include any of these characters 
in a character array, the results are unpredictable. 

The following is useful to display the APL characters in OAV order. 

6 32p32!D4F 
")<<=>] va*t,+./0 12 3456789([;x;\ 
~a±n Le_V A i ° 'Dl ~ro*?p [" -4u ante <->--)■>- 
oABCDEFGHIJKLMNOPQRSTUVWXYZ { h } $ 
'abcdefgfiijXlmnopqrstuvwxyz@"#%& 
kABCDElGHIJKLMNOPQRSTUVUXYZ 'rut 
f?vA®<t>i(e T Ac2=A00D0000 0l]0D 
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Table 2-4 Elements of OA V( rjio«-o) 



dec 





32 


64 


96 


128 


160 


192 


224 





NUL 


SP 


- 





' 


A 


a 


D 


1 


SOH 




a 


A 


a 


A 


B 


D 


2 


STX 


) 


1 


B 


b 


B 


a 


D 


3 


ETX 


< 


n 


C 


c 


C 


a 


D 


4 


EOT 


< 


L 


D 


d 


D 





D 


5 


ENQ 


= 


e 


E 


e 


E 


4 


D 


6 


ACK 


> 


_ 


F 


f 


I 


¥ 


D 


7 


BEL 


] 


V 


G 


g 


G 


V 


D 


8 


BS 


V 


A 


H 


h 


H 


V 


D 


9 


HT 


A 


I 


I 


i 


I 


A 


D 


10 


LF 


* 


• 


J 


J 


J 


« 





11 


VT 


* 


1 


K 


k 


K 


<*> 


D 


12 


FF 


, 


D 


L 


1 


L 


«« 


D 


13 


CR 


+ 




M 


m 


M 


e 


D 


14 


SO 




T 


N 


n 


N 


■ 


D 


15 


SI 


/ 














/ 


D 


16 


DLE 





* 


P 


P 


P 


\ 


D 


17 


DC1 


1 


7 


Q 


<? 


Q 


c: 


n 


18 


DC2 


2 


P 


R 


r 


R 


D 


D 


19 


DC3 


3 


r 


S 


s 


S 


= 


D 


20 


DC4 


1- 


- 


T 


t 


T 


A 


D 


21 


NAK 


5 


+ 


U 


u 


U 


D 


D 


22 


SYN 


6 


u 


V 


V 


V 


D 


D 


23 


ETB 


7 


w 


w 


V 


W 





D 


24 


CAN 


8 


D 


X 


X 


X 


D 





25 


EM 


9 


+ 


Y 


y 


Y 


D 


D 



(continued on next page) 
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Table 2-4 (Cont.) Elements ofnAV(Oio<-o) 



dec 



32 



64 



96 



128 



160 



192 



224 



26 


SUB 


27 


ESC 


28 


FS 


29 


GS 


30 


RS 


31 


US 



z 


z 


z 





D 


{ 


e 


1 


D 


D 


-4 


" 


R 


D 


D 


} 


# 


I 


D 


D 


$ 


1. 


i. 


D 


D 


DEL 


s. 


T 


D 


D 



The index of a character in Q A V is the sum of its row and column numbers. 

Possible Errors Generated 

None. 



2-34 APL Reference Manual 



System Variables and Functions 

QBOX Forming Character Matrices and Vectors 



D BOX Forming Character Matrices and Vectors 
Type 

Ambivalent System Function 

Form 

boxed-text *- ^delimiterj QBOX text 

Left Argument Domain 



Type 


Character 


Shape 


Vector domain 


Depth 


o or l (simple) 


irgumer 


it Domain 


Shape 


Matrix domain 


Depth 


or l (simple) 



Result Domain 



Rank 


1 or 2 


Shape 


Matrix or Vector 


Depth 


l (simple) 


Description 





QBOX produces a character matrix from a character vector or vice versa. 

When the right argument is in the vector domain, UBOX forms a matrix. When 
the right argument is a matrix, QBOX forms a vector. If the right argument 
is an empty vector, the result is an empty character matrix with the shape 
. If the right argument is an empty matrix, the result is a vector containing 
a number of delimiters equal to the number of rows in the right argument 
matrix. 

When producing a matrix, APL uses a delimiter to determine where to form 
rows. The left argument optionally specifies a delimiting string. The default 
delimiter is <CR> <LF> . The number of columns is equal to the longest string 
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contained between any pair of delimiters. Shorter strings are padded with 
trailing blanks. 

When producing a vector with the monadic form, APL removes any trailing 
blanks and inserts the <CR> <LF> delimiter at the end of each row. 

When producing a vector with the dyadic form, APL does not remove trailing 
blanks from the rows of the matrix argument. It does insert the specified 
delimiter at the end of each row. 

D BOX is particularly useful for forming a matrix from a vector consisting of 
lines of data delimited by <CR> <LF> pairs. UBOX removes the <CR> <LF> 
and makes each line of data that was between <CR> <LF> s (or between a 
<CR> <LF> and the end or beginning of the vector) a row in the result matrix. 
Thus, the result matrix and right argument vector appear the same when 
displayed by APL. 

Examples: 

B *■ 'FIRST LINE 
SECOND LINE IS LONGER 

LINE FOUR' 

70 

(34 * UCTRL i B)/ipB ^GENERATE INDEX OF <CR><LF>S 

11 12 48 49 55 56 

pU+UBOX B 
FIRST LINE 
SECOND LINE IS LONGER 

LINE FOUR 
4 35 

ftNO <CR><LF> ADDED TO LAST RON 
pQ+UBOX (UBOX S) 
FIRST LINE 
SECOND LINE IS LONGER 

LINE FOUR 

65 



p0*QBOX 'A' 



A 
1 1 
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^TRAILING <CR><LF> IGNORED 

pU+UBOX 'A' , QCTRL [14 11] 
A 
1 1 

pD-'-r- 1 -',' UBOX >ABC,DE,FGHI< 
ABC 
DE 
FGRI 
3 H 

pD"-'!' UBOX Y 
ABC'.DE'.FGHI 
11 

pU+'AB' UBOX 'XXXABYYYABUV 

XXX 
YYY 
III 
3 3 

pQ«-'ji' UBOX lilp'B 1 
5 
1 1 

pU*-'A< UBOX 1 1 1 p '4' 

(APL outputs a blank line.) 
1 

Possible Errors Generated 

9 RANK ERROR (NOT MATRIX DOMAIN) 

9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 
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D BREAK Suspending Execution 
Type 

Monadic System Function 

Form 

D BREAK apl-expression 

Argument Domain 



Type 


Any 


Shape 


Any 


Depth 


or l (simple) 


Result Domain 




Type 


None 


Shape 


None 


Depth 


None 


Description 





D BREAKsuspends execution of the operation in which it is contained and 
returns you to immediate mode. It takes any APL object as an argument and 
prints the value of that argument before breaking to the terminal. However, 
the function itself has no explicit result. 

To return to execution after a break, you can either branch to a specific line 
number (-*■ 3), or you can use the system function QLC. Use of Die would return 
you to the breakpoint, that is, to the line where the D BREAK executes. To 
resume at the line after the breakpoint, specify QLC+i. For example: 
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VFUNC 




[1] 


'FIRST LINE' 




[2] 


WREAK 'BREAK AT 


LINE 2' 


[3] 


'RESUME AT LINE ; 


!' 


W 


V 
FUNC 




FIRST 


LINE 




BREAK 


AT LINE 2 

+ULC+1 




RESUME AT LINE 3 





It is illegal to use Q BREAK in immediate mode or as part of the argument to 
the execute (± )function. 

Possible Errors Generated 



15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 
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D CHANS Returning Channel Numbers 
Type 



Mladic System Function (query) 


Form 




current-channels 


: +■ D CHANS 


Result Domain 




Type 


Integer 


Rank 


l 


Shape 


Vector 


Depth 


l (simple) 


Description 





D CHANS displays all of the channel numbers currently associated with file 
specifications. The result is a vector. In the following example, channels 1 and 
5 are each associated with a file: 

UASS '1 PLAN /AS' QASS '5 ANALYSIS/ AS' 
1 
5 

UCHANS 
1 5 

) CLEAR 
CLEAR US 

QCHANS 

(APL outputs a blank line) 

If no channels are assigned, Q CHANS returns an empty numeric vector. 

D CHANS is also described in the VAX APL User's Guide along with other file 
I/O information. 

Possible Errors Generated 

None. 
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D CHS Returning File Organization and Open Status 
Type 



Monadic System Function 



Form 



file-org 1 status *- 


D CHS chans 


Argument Domain 




Type 


Near-integer 


Shape 


Vector domain 


Range 


~ 9 9 9 to 999 (but not 


Depth 


or l (simple) 


Result Domain 




Type 


Integer 


Rank 


l or 2 


Shape 


Vector or matrix 


Depth 


l (simple) 


Description 





D CHS returns the file organization and status of the files associated with 
the specified channels. The absolute value of chans represents the channels 
associated with the files you want information on. The following table gives 
the possible codes resulting from Q CHS. 
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First Element 




Second Element 


Code 


File Organization 


Code 


Open Status 





Not applicable 





Channel free 


1 


/AS 


1 


Assigned but not open 


2 


/IS 


2 


Open for output 


3 


Not applicable 


3 


Open for input 


4 


IDA 


4 


Open for input and output 


5 


Not applicable 






6 


Not applicable 






7 


IRF 






8 


IKY 







If the argument is a singleton, D CHS returns a two-item vector: the first item 
identifies the file's organization, and the second item identifies the file's open 
status. For example: 

QCHS 1 
1 3 

This means that the file associated with channel 1 is an ASCII sequential file 
that is assigned and open for input. 

If the argument is a vector of n items, the result is an array of shape n by 2 . 
For example, the following expression returns a 3-by-2 array: 

U*-FILS*-UCHSi3 

1 3 
7 H 

2 2 

pFILS 

3 2 

□ CHS returns a result of 2 p if its argument is empty. 

D CHS is also described in the VAX APL User's Guide along with other file I/O 
information. 

Possible Errors Generated 

9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) 
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15 DOMAIN ERROR (INVALID CHANNEL NUMBER) 
15 DOMAIN ERROR (NOT AN INTEGER) 
2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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D CIQ and □ COQ Packing and Unpacking Data 
Type 

Dyadic System Function 

Form 

unpacked-data ■*- packed-data Q CIQ header fitypej 

Left Argument Domain 



Type 


Near-integer 


Shape 


Vector domain 


Depth 


or l (simple) 


Right Argument Domain 


Type 


Near-integer 


Shape 


Vector domain 


Depth 


o or i (simple) 


Result Domain 




TVpe 


Any 


Rank 


Any 


Shape 


Any 


Depth 


Any 


Type 




Dyadic System Function 


Form 




packed-data *- 


data UCOQ header fttypej 
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Left Argument Domain 



Type 


Any 


Shape 


Any 


Depth 


Any 



Right Argument Domain 



Type 


Near-integer 


Shape 


Vector domain 


Depth 


or 1 (simple) 


Result Domain 




Type 


Integer 


Rank 


1 


Shape 


Vector 


Depth 


1 (simple) 


Parameters 





unpacked-data 

The variable associated with the unpacked data; it must be in the format of the 
result of D COQ, with or without a header. It may be empty only if header is 0. 

packed-data 

Specifies the variable associated with the packed data. 

data 

Any array you want to pack into an integer vector. 

header 

0, 2, or 4. For D CIQ, if a header exists, it is 2; if no header exists, it is 0. If you 
specify and a header does exist, the header is treated as part of the data to 
be unpacked. With □ COQ, use if you do not want a header; 2 if you do want a 
header; and 4 if you want only a header. 

type 

If specified, it indicates whether the data is to be converted to another data 
type before being packed. The possible values are listed in Table 2-5. The 
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possible effects of such a conversion are summarized in the VAXAPL User's 
Guide. Omitting type has the same effect as using type 0. 

Description 

D CIQ and D COQ allow you to accumulate data of different types into variables. 
You can then catenate the variables for storage as one logical record. 

D COQ takes an argument of any data type and packs it into an integer vector 
by treating it as if it were a stream of bits. For example, you can put ASCII 
characters in one variable and internal APL characters in another variable, 
then catenate them, and write them to a file. Later, you can read the file and 
use D CIQ to change the variables from integer vectors back into ASCII and 
APL characters. 

The value of D COQ is the packed data or, if the header parameter equals 4, the 
header information associated with the left argument. 

The value of CIQ is the unpacked data. Q CIQ converts the packed data 
to the internal data type specified by the corresponding external data type 
identified by the type parameter (the possible effects of such a conversion are 
summarized in the VAXAPL User's Guide.) 

Table 2-5 Type Parameter Values 



Type External Data Type 



No conversion; use type of "data" 

1 Convert to 32-bit integer 

2 Convert to 1-bit Boolean 

3 Convert to F_floating single-precision floating-point 
M- Convert to D_floating double-precision floating-point 

5 Convert to 8-bit 2 AV characters 

6 Convert to 8-bit ASCII characters 

7 Convert to 8-bit unsigned numeric bytes 

8 Convert to G_fioating double-precision floating-point 

9 Convert to H_floating floating-point 

10 Convert to 16-bit integer 

1 1 Convert to 8-bit Digital Multinational Characters 

(continued on next page) 



2-46 APL Reference Manual 



System Variables and Functions 

D CIQ and D COQ Packing and Unpacking Data 



Table 2-5 (Cont.) Type Parameter Values 



Type 



External Data Type 



1 2 Convert to 8-bit UAV characters in TTY mnemonics 

1 3 Convert to 8-bit D A V characters in KEY-paired APL 

1 4 Convert to 8-bit UAV characters in BIT-paired APL 

1 5 Convert to 8-bit Q A V characters in APL COMPOSITE 

The header generated by D COQ has the following format: 



length 



type 



rank 



(pdataJM 



(pdata)[2] 



(pdata)[rank] 



NU-2234A-RA 

Each large box represents a longword as described in the following list: 

• length is the length of the integer vector result of Q COQ 2 

• type is one of the external types in Table 2-5 

• rank is the rank of the data that was packed by Q COQ 

The next n (n - rank) boxes contain the shape of the data that was packed. 
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For example: 

4<-i5 

P<-A QCOQ 2 

P 
91151231(5 

B<-3 *pl 

B 
10 10 
10 10 
10 10 

Q+-B QCOQ 2 

Q 
6 2 2 3 4 1365 

B00Z>(32p2)Tl365 

"12 t BOOL 
010101010101 

P QCIQ 2 
12 3 4 5 

QCIQ 2 
10 10 
10 10 
10 10 

The first example uses □ COQ to pack the vector i 5. The value of P shows that 
when i 5 was packed, the packed data had length 9 (including the header), 
type 1 (integer), rank 1, and shape 5. 

In the second example, the Boolean matrix B is packed into Q . The value of Q 
indicates that the packed data with its header has length 6, type 2 (Boolean), 
rank 2, and shape 3 4. Note that when Q [ 6 ] is converted to Boolean, the value 
is the same as that of <t> , B (the Boolean data values are stored right to left). 

Finally, □ CIQ was used to unpack the data, to retrieve the data and translate 
it back to the original data. 

In the following example, the functions PACK and UNPACK use QCOQ and UCIQ 
to pack and unpack values of different types: 
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VP+PACK LIST -J 

[I] nPACK USES UCOQ TO PACK A SET OF VALUES 

[2] aINTO A SINGLE VARIABLE. THE VALUES CAN BE 

[3] ^DIFFERENT TYPES OR SHAPES. THUS, YOU CAN 

W zUSE PACK WHEN CATENATE WON'T WORK. 

[5] nLIST IS A CHARACTER MATRIX, EACH ROW OF WHICH 

[6] ^CONTAINS THE NAME OF A VARIABLE WHOSE VALUE 

[7] nIS TO BE PACKED. 

[8] hP IS THE RESULTANT PACKED VALUE; IT IS AN 

[9] a INTEGER ARRAY. 

[10] p 

[II] P+iO 
[12] Jt-1 

[13] TEST:+(I>lipLIST)/0 

[lit] P^P, [iLISTU;l)UCOQ 2 

[15] I>I+1 

[16] +TEST 

[17] V 

VP UNPACK LIST;DATA;I;J;LEN;ENTRY 

[I] aUNPACK USES UCIQ TO UNPACK A VARIABLE CREATED 
[2] rBY PACK INTO A SET OF VARIABLE NAMES. 

[3] fiP IS THE PACKED VALUE, CREATED BY PACK. 

[4] ftLIST IS A CHARACTER MATRIX, EACH ROW OF WHICH 

[5] ^CONTAINS THE NAME OF A VARIABLE TO RECEIVE ONE 

[6] dOF THE PACKED VALUES. UNPACKED VALUES FROM P 

[7] RARE STORED INTO SUCCESSIVE VARIABLES IN LIST. 

[8] DATA+P 

[9] I+pDATA 

[10] J+l 

[II] TEST:+(I<0)/0 
[12] +(J>l+pLIST)/Q 
[13] LEN+DATAIU 

[It] ENTRY+DATA liLENl 

[15] i LISTU;], GENTRY QCIQ 2' 

[16] DATA+LEN 4- DATA 

[17] J^J+1 

[18] I+I-LEN 

[19] +rs5r 

[20] V 

P DEFINE SOME NUMERIC VARIABLES: 
A+l 

AA*- 1 1 
4^4-*- 111 

aDEFINE SOME CHARACTER VARIABLES: 

BB<-'BB' 
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aMAKE A LIST OF INPUT VARIABLE NAMES: 
Ll-f-5 3p 'A AA AAAB BB ' 
LI 
A 

AA 
AAA 
B 
BB 

aPACK THESE VARIABLES INTO ONE ITEM 
a CATENATE WON'T WORK 
REPACK LI 
P 
420152123452137450 98 5512 25186 

oMAKE A LIST OF OUTPUT VARIABLE NAMES: 
12+5 3p'X XX XXXJ YY ' 
12 
X 

XX 
XXX 
Y 
Y 

nUNPACK THE PREVIOUS DATA INTO NEW VARIABLES: 
P UNPACK 12 

aTBE RESTORED DATA IS THE SAME AS THE 
a DATA THAT WAS PACKED. 
X=A 



1 
1 1 

1 1 1 
1 
1 1 



XX=AA 
XXX-AAA 
Y=B 
YY-BB 



Possible Errors Generated 

For □ CIQ: 

9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (ARGUMENT MUST BE 1 OR 2 ELEMENTS) 
10 LENGTH ERROR (DATA TYPE MISSING) 

10 LENGTH ERROR (DATA TYPE EXCEEDS DATA LENGTH) 
15 DOMAIN ERROR 
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15 DOMAIN ERROR (DATA TYPE MUST BE UNSPECIFIED OR ZERO) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (INVALID CIQ HEADER) 

15 DOMAIN ERROR (INVALID EXTERNAL DATA TYPE) 

15 DOMAIN ERROR (INVALID HEADER TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
For D COQ: 

9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (ARGUMENT MUST BE 1 OR 2 ELEMENTS) 
15 DOMAIN ERROR 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (INVALID HEADER TYPE) 

15 DOMAIN ERROR (INVALID EXTERNAL DATA TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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UCLS Closing Files 
Type 

Monadic System Function (quiet) 

Form 

i ■*- QCLS chans 

Argument Domain 



Type 


Near-integer 


Shape 


Vector domain 


Depth 


or l (simple) 


Value 


~ 9 9 9 through 9 9 9 (but not ) 


Result Domain 




Type 


Numeric 


Rank 


1 (vector) 


Shape 


(empty) 


Depth 


l (simple) 


Description 





D CLS closes one or more files without deassigning their corresponding 
channels. The absolute values of chans represent the channels associated 
with the files you want to close. 

D CLS is useful when you want to return to the beginning of a sequential file. 
(You can also use the D REWIND system function, which does not close files.) 

After you close a channel, a read function opens the file and reads the first 
record, and a write function creates a new version of the file (except for /DA, 
/RF, and /KY files, where a new file is created only if no version currently 
exists). With Q CLS, there is no need to reassign the file to the channel. 

The following line closes the file associated with channel 2: 

UCLS 2 

Any unassigned channels in the argument are ignored. 
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D CLS is a quiet function; it does not return a result if it is the leftmost function 
in a statement. When Q CLS is not the leftmost function, it returns an empty 
numeric vector. If its argument is empty, Q CLS has no effect. 

Note that when you use Q CLS, you activate whichever parameter has 
been set for the /DISPOSE qualifier on BASS. For example, if you specify 
/DISPOSE -.DELETE, APL deletes the file when you specify the D CLS function. 

APL automatically closes and deassigns all open files when you press Ctrl/Z 
or execute a )LOAD, ) CLEAR, )OFF, or ) CONTINUE system command (the )MON 
and ) PUSH system commands do not have this effect). 

D CLS is described in the VAX APL User's Guide along with other file I/O 
information. 

Possible Errors Generated 



9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INVALID CHANNEL NUMBER) 

15 DOMAIN ERROR (NOT AN INTEGER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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D CR Obtaining a Canonical Representation 
Type 

Monadic System Function 

Form 

canonical-rep ■*■ Q CR operation-name 

Argument Domain 



Type 


Character 


Shape 


Vector domain 


Depth 


or 1 (simple) 


Result Domain 




Type 


Character 


Rank 


2 


Shape 


Matrix 


Depth 


l (simple) 



Implicit Arguments 

D PP (controls precision of numeric constants) 

Description 

D CR provides a canonical representation of a user-defined operation, which 
enables you to treat the operation as data. A canonical representation is 
a character matrix with rows that are the original lines of the operation 
definition, but are reformatted so that they are the same length. 

The canonical representation consists of exactly what you typed when you 
defined the operation, minus the beginning and ending ? s, plus blanks added 
to the end of lines to make their lengths the same as that of the longest line 
of the operation. Line numbers and brackets are removed from the definition. 
White space at the beginning (but not at the end) of a line is preserved. Lines 
that contain labels are not shifted. 
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The argument of the D CR system function is a character array representing 
the name of the operation. The shape of the argument must be in the vector 
domain. 

If the argument is empty or does not represent the name of an existing 
unlocked operation, the resulting character matrix is an empty matrix, with 
the shape 0. (APL considers primitive system functions and external 
functions as locked.) 

The display of numeric constants in an operation definition is D PP-dependent. 

□ CR does not work on operands to user-defined operators that contain derived 
functions. Use □ VR instead. 

For example: 

VMEANX+NSUBJ MEAN X 
[1] nSUM VECTOR X 
[2] SVMX++/X 
[3] MEANX-SUMX+NSUBJ 
W V 

D «- SHONCRFX <- UCR 'MEAN' 
MEANX+-NSUBJ MEAN X 
r>SUM VECTOR X 
SUMX++/X 
MEANX+SUMXiNSUBJ 

p SHONCRFX 
H 21 

X*- 8 6 3 9 5 4 2 1 7 4 

10 MEAN X 
k.9 

The D FX system function is the inverse of Q CR. 

Possible Errors Generated 



9 RANK ERROR [NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 
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□ CT Comparison Tolerance 
Type 



System Variable 



Form 



□ CT -*- tolerance-value 


floating-scalar * 


- OCT 


Value Domain 




Type 


Non-negative numeric 


Shape 


Singleton 


Depth 


or l (simple) 


Value 


to 2.3 2 8£~10 


Default 


Iff" 15 


Result Domain 




Type 


Numeric 


Rank 





Shape 


i (scalar) 


Depth 


(simple) 



Description 

D CT specifies the degree of tolerance applied when two numbers are compared 
for equality. If the difference between two numbers is less than or equal to the 
value of D CT times the larger number, the numbers are considered equal. 

The value of D CT affects the following primitive functions: 



Function Function Name 



Function Function Name 



e Set membership 

i Index of 

> Greater than 



Residue 

Ceiling 

Floor 
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Function 


Function Name 


Function 


Function Name 


> 


Greater than or equal to 


u 


Set union and unique 


= 


Equal to 


n 


Set intersection 


* 


Not equal to 


~ 


Without 


< 


Less than or equal to 


c 


Subset 


< 


Less than 


z> 


Contains 


= 


Match 


i 


Matrix inverse and divide 



The value of CT is saved when you save the active workspace and can be 
localized in user-defined operations. 

For example: 

UCT 
IE" 15 

1 = 1.00000000009 


QCT<-1£"10 

1 = 1.00000000009 

1 

The following function is the APL metafunction. It describes an exact definition 
of how □ CT is applied. 

Vz<-4 DFEQ B ;UCT;T r>A=B WITHIN BXCT 
[1] QCT+-0 
[2] T*0<(xA)B 
[3] A+A*T 
[4] B+BxT 
[5] Z+-(U-fl)<DCTx(U)NB 

[6] z^zxr v 
Possible Errors Generated 

9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (NOT SINGLETON) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (PARAMETER OUT OF RANGE) 
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□ CTRL Control Characters 
Type 

Niladic System Function 

Form 

control-chars ■*- □ CTRL 

Result Domain 



"type 


Character 


Rank 


l (vector) 


Shape 


33 


Depth 


l (simple) 


Description 





DCTRL is a subset of UAV. It returns a vector of the 32 ASCII control characters 
and Delete, or, expressed in terms of D A V: 

UAVli32,UI0+127l 

The control characters are listed in the table below. Note that for any 
formatting control character, the internal code that appears in CTRL is 
the same as the internal code used by APL for that character. For example: 

QI(K0 o UAV i 'ABCDEF' 
97 98 99 13 10 32 32 32 32 32 100 101 102 



Index 


Name 


Description 


Octal Value 


Hex Value 





NUL 


Null 


000 


00 


1 


SOH 


Start Of Heading 


001 


01 


2 


STX 


Start of TeXt 


002 


02 


3 


ETX 


EndofTeXt 


003 


03 


4 


EOT 


End Of Transmission 


004 


04 


5 


ENQ 


ENQiry 


005 


05 
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Index 


Name 


Description 


Octal Value 


Hex Value 


6 


ACK 


ACKnowledge 


006 


06 


7 


BEL 


BEL1 


007 


07 


8 


BS 


Backspace 


010 


08 


9 


HT 


Horizontal Tabulation 


011 


09 


10 


LF 


<LF> 


012 


0A 


11 


VT 


Vertical Tabulation 


013 


0B 


12 


FF 


Form Feed 


014 


oc 


13 


CR 


<CR> 


015 


0D 


14 


SO 


Shift Out 


016 


0E 


15 


SI 


Shift In 


017 


OF 


16 


DLE 


Data Line Escape 


020 


10 


17 


DC1 


Device Control 1 


021 


11 


18 


DC2 


Device Control 2 


022 


12 


19 


DC3 


Device Control 3 


023 


13 


20 


DC4 


Device Control 4 


024 


14 


21 


NAK 


Negative AcKnowledge 


024 


15 


22 


SYN 


SYNchronous Idle 


026 


16 


23 


ETB 


End-of-Transmission Block 


027 


17 


24 


CAN 


CANcel 


030 


18 


25 


EM 


End of Medium 


031 


19 


26 


SUB 


SUBstitute 


032 


1A 


27 


ESC 


ESCape 


033 


IB 


28 


FS 


File Separator 


034 


1C 


29 


GS 


Group Separator 


035 


ID 


30 


RS 


Record Separator 


036 


IE 


31 


US 


Unit Separator 


037 


IF 


32 


DEL 


DELete 


177 


7F 



Possible Errors Generated 

None. 
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□ DAS Deassigning Files 
Type 

Monadic System Function (quiet) 

Form 

x +- QDAS charts 

Argument Domain 



Type 


Near-integer 


Shape 


Vector domain 


Depth 


o or l (simple) 


Value 


~ 9 9 9 through 9 9 9 (but not ) 


Result Domain 




T>pe 


Numeric 


Rank 


l (vector) 


Shape 


o (empty) 


Depth 


l (simple) 


Description 





QDAS dissociates or deassigns file specifications from channel numbers. The 
absolute value of chans represents the channels associated with the files you 
want to deassign. If any files associated with the specified channel numbers 
have not been closed (by Q CLS), QDAS closes them, and then deassigns them. 

In general, QDAS reverses the operations performed by the 2 ASS system 
function. The following line deassigns the files associated with channels 1, 3, 
and 5: 

[]DAS 1 3 5 

Any unassigned channels in the argument are ignored. 

QDAS is described in the VAX APL User's Guide along with other file I/O 
information. 
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Possible Errors Generated 



9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR {ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INVALID CHANNEL NUMBER) 

15 DOMAIN ERROR (NOT AN INTEGER) 

27 LIMIT ERROR (INTEGER TOO LARGE) 
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UDC Display Control 
Type 

System Variable 

Form 

D DC ■*■ display-area box-characters 
current-setting ■*- UDC 



Value Domain 




Type 


Enclosed, heterogeneous (see below) 


Shape 


2 (vector) 


Depth 


2 or 3 (enclosed) 


Default 


("1102) ' ' 



Result Domain 



Type 


Enclosed, heterogeneous 


Rank 


1 


Shape 


2 (vector) 


Depth 


2 or 3 (enclosed) 



Description 



UDC specifies how APL displays enclosed arrays. You can set UDC to draw 
boxes around enclosed items of an array, and the resulting display makes the 
nested structure of the array clearer. You can also increase the blank space 
that APL uses to surround an enclosed item. 

The value you assign to UDC is a two-item enclosed vector. 

The first item of the UDC value is a simple numeric vector of length 4. Data 
elements 1 and 2 of this item specify where an item is displayed when its 
display area is larger than the structure of the item itself. The first data 
element controls the vertical placement; the item can be at the top, center, or 
bottom of the display area. The second data element controls the horizontal 
placement; the item can be at the left, center, or right of the display area. The 
following table describes the meaning of the values you can specify for these 
two data elements: 
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Positioning 


Items in Display Areas 




First Element 


Location 


Second Element 


Location 


"1 

1 


Top 

Center 

Bottom 


"1 



1 


Left 

Center 

Right 



Data elements 3 and 4 of the first item of the QDC value allow you to change 
the size of the display areas. The third data element controls the vertical space 
between rows of items; the integer you specify indicates how many blank rows 
you want to add. The fourth element controls the horizontal space between 
columns; the integer you specify indicates how many blank columns you want 
to add. (Note that the rows and columns containing the characters that form 
the boxes are included in the number you specify. When you display boxes, the 
minimum value you can specify for the third and fourth elements is 2 .) The 
default for the third and fourth elements are (no extra rows between rows of 
items) and 2 (two extra columns between columns of items), respectively. 

The second item is a character vector that is either empty ( ' ' ), if you do not 
want boxes around enclosed items, or has length 8. The vector specifies the 
characters for APL to use when it draws boxes around enclosed items. The 
first four items specify the symbols for the corners of boxes (upper left, upper 
right, lower left, lower right), the next two items specify the left and right 
sides, and the last two specify the top and bottom. 

The following table describes the order and meaning of the eight items in the 
second item of the UDC value: 



Position 


i in 


Portion of Box 




Second 


Item 


Described 


Shape 


1 




Upper left corner 


Singleton 


2 




Upper right corner 


Singleton 


3 




Lower left corner 


Singleton 


4 




Lower right corner 


Singleton 


5 




Left side 


Vector 
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Position in 
Second Item 



Portion of Box 
Described 



Shape 



6 


Right side 


7 


Top 


8 


Bottom 



Vector 
Vector 
Vector 



The default value of DOCis ("1102) ' ' . The four data elements of the 
non-empty item have the following meanings: ~ l positions data at the top 
of each display area, l justifies data to the right, places no extra blank 
lines between rows of data, and 2 places an extra blank between columns of 
enclosed items. For example: 



TIME' 98 23 <C0MIN< 



<Y0< 



D*-CSffr-i-3 3p'L0HG' 9823 834 

+ + 9823 834 

| LONG | 

+ + 

+ + 98 23 

\TIME\ 

+ + 

+ + "2 +-- + 

| COMIN | | 70 | 

+ + +-- + 

D-HWSOU 2) (345) 6 (789 10) 

+ + + + 6 + + 

| 1 2| | 3 M- 5 | |789 10 
+ + + + + + 

^WITHOUT EXTRA BLANKS, MUSC WOULD APPEAR AS i 10 

ilO 
1 2 3 4 5 6 7 8 9 10 

The displays that follow show CSNY and MUSC with the addition of the delta 
(A ) symbol to clarify the location of the blanks. 

ALO/VGAA9823AA834 
AriM£AAAA98AAA23 
COMIffAAAA~2AAA70 

1A2AA3A4A5AA6AA7A8A9A10 

The following examples describe the use of the second item of the ODC value, 
which specifies the boxes for APL to draw. If you specify ' ++++ | | = = ' as the 
second item, APL draws boxes that look like the following: 
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The items you specify for the corners of boxes must be singleton items. 
However, the four sides may be character strings (vectors). (Note that the 
depth increases from two to three when you specify a character string for one 
or more of the four sides.) For example, if you specified ' + ' ' + ' ' + ' ' + ' ' \ / ' 
1 \ / ' ' PETER < ' PETER ' as the second item of the □ DC value, APL would draw 
boxes that look like the following: 

+PETER+ 
\ \ 

I I 

+PETER+ 

If a dimension of the box requires fewer characters than the string you specify, 
APL uses only the number required. If the box requires more characters, APL 
reuses the string. For example, the boxes might look like the following: 



+PET+ 




\ \ 




+PET+ 




+PETERPET+ 


\ 


\ 


1 


1 


\ 


\ 


1 


1 


+PETERPET+ 



When APL displays an array, it places each item of the array into a display 
area. If all items have the same shape, the display areas are all the same size. 
If the items vary in shape (as they often do), the display areas also vary in size. 
For any given row, the vertical dimension of the display area is determined by 
the maximum number of rows in any item in that row. For any given column, 
the horizontal dimension of the display area is determined by the maximum 
number of columns in any item in that column. For example: 
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ODC 
+ + + + 

n "i 2 31 I++++M-I 

+ + + + 

BUMP+2 2p( ilO) 5 (3 4p 1 12) 'ABC 

BUMP 
+ + 5 

1123456789 10 | 

+ + 

+ + + + 

|1 2 3 t| \ABC\ 

1 5 6 7 8 1 +--- + 

|9 10 11 12 j 

+ + 

Note the dimensions of the display areas in the preceding example. 
B UMP [ l ; l ] ( <= i i o ) determines the dimension for the first column because it 
is wider than BUMP[2 ;l](c3 4p i 12 ). BUMP12 ; 2] determines the dimension 
for the second column because it is wider than BUMP ll; 2] ( 5 ) . BUMP 11% 1] 
determines the dimension for the first row because it has more rows than 
BUMP ll; 21 (the rows of the box are part of the display size of B UMP [ 1 ; 1 ] ). 
Finally, BUMP [2 ; l] determines the dimension for the second row because it 
has more rows than BUMP [2 ; 2] ( c ' ABC < ) . 

Note that this manual displays enclosed items as if the ODC default were the 
following: 

UDC 

+ + + + 

|"1 "1 2 3| I++++I I — | 
+ + + + 

The UDC setting shown in the preceding example places items in the top left 
corner of each display area, adds two extra rows between rows of items, adds 
three extra columns between columns of items, and draws boxes using plus 
signs, vertical bars, and hyphens. 

Examples: 

QDOO "1 2 3) '++++| |--' 

UDC 

+ + + + 

|"1 "1 2 3| I++++U-I 
+ + + + 

BVMP+2 2p ( 1 10) 5 (3 M-p 1 12 ) 'ABC 

a CHANGE POSITION IN DISPLAY AREA 
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QDC+{0 2 3) '++++I |--' 

UDC 
+ + + + 

! 2 3 1 I++++I | — | 

+ + + + 

BUMP 
+ + 

|1 2 3 t 5 6 7 8 9 10 1 5 
+ + 

+ + 

|1 2 3 M +---+ 

|5 6 7 8| \ABC\ 

|9 10 11 12 1 +--- + 

+ + 

ftCHANGE SIZE OF DISPLAY AREAS 

UDC+{0 OH) '++++| |--' 

UDC 
+ + + + 

|0 H 5| I++++I I--I 
+ + + + 

sUDC 

2 

BUMP 
+ + 

1123156789 10 | 5 
+ + 



+ + 

|1 2 3 H\ +— + 

|5 6 7 8| UBC| 

|9 10 11 12 | +---+ 

+ + 

nCHANGE BOX, REDUCE DISPLAY AREA USE E FOR ELEMENT 1 

b OF SECOND ITEM, F FOR ELEMENT 8 OF SECOND ITEM 

E+-'--p ' 

J-*-'— v ' 

QDC+{0 2 3) (' + ' ' + ' ' + ' ' + ' ' I' ' I ' E F) 

+ __p p p + 

+--p + | +— p + +--P +1 

|0023| |+ + + + | | I— p 1 I--V 1| 

+ ._V + | +--V + +--V +1 

+ __V v V + 



bQDC 
3 
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BUMP 
+ ..p p + 

1123456789 10 | 5 
+ __ 7 y + 

+ ~P + 

|1 2 3 H\ +— p + 

|5 6 7 8| \ABC\ 

|9 10 11 12 J +--V + 

+ --? + 

p STOP DRAWING BOXES 
QDC+iO 2 3) " 
BUMP 
123156789 10 5 



12 3 4 

5 6 7 8 ABC 

9 10 11 12 

QDC+O "1 2 3) '++++| I — 1 

B<-4 o O i5 o fl-«-2 2p <ABCD' 

U+A+cA+B, (cC), eD 
+ + 

h + + +--+i 

I |1 2 3 4 5 | |4B | j 
| + + | OT| | 

+--+I 
+ + 

rTHE following works well to display nests of vectors 
p IN_A form similar to strand notation. 

DOC-i-(0 "1 1)(' + ' ' + ' ' + ' ' + ' '(' ')' " ") 

A 
(1 (1 2 3 4 5) [AB)) 
( [CD)) 

rtTHE FOLLOWING PUTS PARENTHESES AROUND ARRAYS 

QDO(0 2 3) ('/' '\ ' <\< '/' ' | ' ' I ' ' ' ' ') 

A 
I \ 

I / \ / \l 

I 4 |1 2 3 4 5 | |AB | | 
I \ /ICON 

I \ /I 

\ / 



Possible Errors Generated 

9 RANK ERROR [MUST BE VECTOR) 
9 RANK ERROR {NOT SINGLETON) 
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9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (DISPLAY CONTROL ITEM WRONG LENGTH) 

10 LENGTH ERROR (DISPLAY CONTROL VECTOR MUST BE TWO ITEMS) 

10 LENGTH ERROR (NOT SINGLETON) 

15 DOMAIN ERROR 

15 DOMAIN ERROR (ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (ENCLOSED VALUE REQUIRED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NEGATIVE INTEGER NOT ALLOWED) 

15 DOMAIN ERROR (PARAMETER OUT OF RANGE) 
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□ DL Delaying Execution 
Type 





Monadic System Function 


Form 








actual-delay ■*- 


DDL seconds 


Argun 


lent Domain 






Type 


Numeric 




Shape 


Singleton 




Depth 


or l (simple) 




Value 


seconds < ~ 1+2*18 



Result Domain 



Type 


Non-negative numeric 


Rank 





Shape 


i o (scalar) 


Depth 


(simple) 


Description 





D DL delays execution for the number of seconds specified in the argument. If 
the argument is less than 0.001, there is no delay. If the argument is negative, 
there is no delay. 

Although DDL specifies the desired duration of the delay, the actual delay may 
be longer because of other demands on the system. The result returned is the 
actual delay in seconds. For example: 



9 


□ «- QDL 8.5 


fiSET DELAY AND DISPLAY 





D *■ DDL "74.36 


^NEGATIVE ARG = NO DELAY 



Here, the user instructed APL to wait 8.5 seconds before prompting for input; 
the actual delay was 9 seconds. 
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The □ DL function uses a negligible amount of computer time. Thus, you 
can issue it freely when tests are required at periodic intervals to determine 
whether an event has occurred as expected. 

The delay resulting from the execution of Q DL may be canceled by the weak 
attention signal. When the weak attention signal is thus used, APL stops UDL 
and returns the actual delay but does not signal attention. 

Possible Errors Generated 



9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (NOT SINGLETON) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

27 LIMIT ERROR (DELAY VALUE TOO LARGE) 



DECLIT AA VAX 6V09C 

VAX APL reference manual 
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□ DML Maximum Record Length 
Type 



System Variable 




Form 




UDML ■*- default-length 
integer-scalar *■ UDML 


Value Domain 




Type 

Shape 

Depth 

Value 

Default 


Near-integer 

Singleton 

or l (simple) 

512 through 2 0ii8 (bytes) 

201+4- 



Result Domain 



Type 
Rank 
Shape 
Depth 


Integer 



i (scalar) 

(simple scalar) 


Description 





D DML specifies the default maximum record length to be used when you save 
a workspace or create an external file. The value of UDML is saved with the 
workspace and can be localized within user-defined operations. 

If you do not want to use the default maximum record length, you can use the 
/MAXLEN qualifier when you save a workspace or create an external file. If 
you omit the /MAXLEN qualifier, APL uses the value of UDML as the maximum 
record length. 
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Possible Errors Generated 

9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (NOT SINGLETON) 

15 DOMAIN ERROR {ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

15 DOMAIN ERROR (PARAMETER OUT OF RANGE) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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□ D VC Returning Device Characteristics 
Type 

Monadic System Function (query) 

Form 

characteristics *■ DDVC charts 

Argument Domain 



Type 


Near-integer 


Shape 


Vector domain 


Depth 


o or l (simple) 


Value 


~ 9 9 9 through 9 9 9 (but not ) 


Result Domain 




Type 


Integer 


Rank 


l or 2 


Shape 


Vector or matrix (n by 2 ) 


Depth 


l (simple) 


Description 





DDVC displays device characteristics. The absolute value ofchans represents 
the channels associated with the files you want information on. 

For each channel specified in the argument, DDVC returns one row containing 
two values. The first value is the VMS device-characteristics longword, and the 
second value is always . For unassigned channels, DDVC returns o. 

DDVC returns a two-element vector if a single channel is specified. If more 
than one channel is specified, the result is a matrix of shape n by 2 , where n is 
the length of the argument. 

If its argument is empty, DDVC returns a result of o 2p 0. 

Note that to return a value for DDVC, APL must open files that have been 
associated with channels but have not yet been opened. Thus, unopened files 
associated with channels identified by positive integers in the DDVC argument 
are opened for input; unopened files associated with channels identified in the 
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argument by negative integers are opened for output. Note that when you open 
a sequential file for output, APL makes a new copy of the file with a version 
number that is one higher than that of the previous copy. 

It is usually helpful to convert the device-characteristics longword to binary 
format before examining it. For example: 



UASS '15 DESIGN /DA' 



15 



'XXXYYY<Q 15 

A+QDVC 15 

A 
474824712 

(32pl)Ti[l] 
00011100010011010100000000001000 

(-UI0)+U0M (32p2)T J 4[l] 
3 4 5 9 12 13 15 17 28 

You can compare the binary value of the longword with the device 
characteristics in Table 2-6. The first element in the table is associated 
with the rightmost bit in the longword, the second element is associated with 
the next rightmost bit, and so forth. Thus, in the previous example, the three 
rightmost Os indicate that the device is not record-orientated, is not a carriage- 
control device, and is not a terminal; the 1 in the fourth position from the right 
indicates that the device is directory-structured. 

Table 2-6 Device Characteristics Longword 

Bit Type or Condition of Device 

Record-oriented 

1 Carriage-control 

2 Terminal 

3 Directory-structured 

4 Single directory-structured 

5 Sequential, block-oriented 

6 Being spooled 

7 Operator console 

8 RA50,RA81,RA82,RH60 
9-12 (Bits reserved) 

(continued on next page) 
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Table 2-6 (Cont.) Device Characteristics Longword 



Bit Type or Condition of Device 



13 Network 

14 File-oriented 

15 (Bit reserved) 

16 Shareable 

17 Generic 

18 Available for use 

19 Mounted 

20 Mailbox 

21 Marked for dismount 

22 Error logging enabled 

23 Allocated 

24 Non-file-structured 

25 Software write-locked 

26 Capable of providing input 

27 Capable of providing output 

28 Allows random access 

29 Real-time 

30 Read-checking enabled 

31 Write-checking enabled 

Possible Errors Generated 



9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (ENCLUDES ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (NOT AN INTEGER) 

15 DOMAIN ERROR (INVALID CHANNEL NUMBER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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D EFR U EFS UEFC Event Flag System Functions 
Type 



Form 



Monadic System Functions 

event-flag-values *- UEFR chans (read) 
previous-values *■ Q EFS chans (set) 
previous-values +- UEFC chans (clear) 



Argument Domain 



TVpe 


Near-integer 


Shape 


Vector domain 


Depth 


or 1 (simple) 


Value 


"999 to 999 (but not ) 



Result Domain 



Type 


Numeric 


Rank 


1 or 2 


Shape 


Vector or matrix {n by 2 ) 


Depth 


l (simple) 


Description 





There are three event-flag-system functions: Q EFR to read event flag values, 
D EFS to set event flags (make them equal l ), and Q EFC to clear event flags 
(make them equal ). 

The absolute values of chans represent the channels associated with the event 
flags you want to manipulate. 

The Q EFR function returns the values of the event flags associated with the 
channel numbers in its argument. For channels not associated with an event 

flag, QEFR returns " 1. 
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The result is a matrix (or vector, if the argument is a singleton) of shape n 1, 
where n is the shape of the argument. In the example, the result indicates 
that the event flags are associated with channels 1, 2, and 5. The event 
flag associated with channel 2 is set, and then cleared, and no event flag is 
associated with channel 4: 



UASS ' 1 MYFILE I RF I SHARE /EFE: IT 

DASS '2 PUBLIC /DA/ SHARE /EFN-.6B' 

UASS <H MIRE/ IS' 

DASS '5 MAILBOX/ AS/ SHARE /MBX/EFN-.S5' 

QEFS 2 

UEFRi5 



UEFC 2 
QEFRiS 



The DEFS and UEFC functions set and clear, respectively, the event flags 
associated with the channel numbers in their arguments. They return a 
matrix of shape n by 1, where n is the shape of the argument, and the values 
are the previous values of the event flags. For channel numbers not associated 
with event flags, QEFS and UEFC return ~ 1. 

If the argument to QEFR, QEFS, or UEFC is empty, APL returns lp as the 
result. 

DEFR, DEFS, and UEFC are described in the VAX APL User's Guide along with 
other file I/O information. 
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Possible Errors Generated 

9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (NOT AN INTEGER) 

15 DOMAIN ERROR (INVALID CHANNEL NUMBER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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□ ERROR Error Message 
Type 

System Variable 

Form 

+■ D ERROR 

D ERROR *- error-text 

Value Domain 



Type 


Character 


Shape 


Vector domain 


Depth 


or l (simple) 


Default 


t T 



Result Domain 



Type 


Character 


Rank 


l 


Shape 


Vector 


Depth 


l (simple) 


Description 





UERROR contains either the text of the last error message that occurred or the 
text that you assign to it. (Q ERROR is set implicitly by the system when an 
error occurs, but can also be set by the user.) QERROR contains one error at a 
time; when a new error occurs, the new message overwrites the old one. You 
can, however, localize Q ERROR within user-defined operations to save error 
information within an operation's own environment. 

The text of Q ERROR is a character vector of variable-length lines and is 
delimited by a <CRxLF>. The lines of text in Q ERROR are the same as the 
lines of the error message that APL displays on the terminal (except when 
□ TERSE is 1), including secondary error messages and execute error messages. 
The error number is always contained in the first four characters of Q ERROR, 
so you can always extract the error number with the expression int QERROR. 
Q ERROR always contains the entire error message text, even if some of the text 
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was not displayed on the terminal because it was truncated to Q PW characters. 
For a description of the text of error messages, see Appendix A. 

Note that like all the system variables, Q ERROR can be set by the user; that is, 
you can use the specification function (V4 ) to assign a value to it. 

It is possible that when a WORKSPACE FULL error occurs, there will not be 
enough memory available to build Q ERROR. In that case, Q ERROR will equal ' ' 
(an empty character array). It is also possible that there will not be enough 
room to display D ERROR. In that case, APL signals WORKSPACE FULL with the 
line in error being D ERROR. 

For example: 

VABCiUTRAP-.QERROR ^LOCALIZE UTRAP AND UERROR 
[1] UTRAP-*-'* LAB' 
[2] 5+ 

[3] nNEXT LINE PRINTS MESSAGE AND INTERRUPTS EXECUTION 

[t] LAB-.QBREAK 'CHECK ERROR MESSAGE' 
[5] 'RESUME AT LINE 5' 
[6] V 

nNOW GENERATE AN IMMEDIATE MODE ERROR 

C+A «ADD TUO UNDEFINED VARIABLES 

11 VALUE ERROR 

C+A a ADD TWO UNDEFINED VARIABLES 

A 

(f CHECK GLOBAL VALUE OF UERROR 
UERROR 
11 VALUE ERROR 

C+A fiADD TUO UNDEFINED VARIABLES 

A 

oNOW EXECUTE ABC TO GENERATE LOCAL ERROR 
ABC 
CHECK ERROR MESSAGE 

oABC HAS SUSPENDED 
»N0U CHECK CONTENTS OF UERROR 
UERROR 
1 SYNTAX ERROR (RIGHT ARGUMENT TO FUNCTION MISSING) 
ABC12] 5 + 

A 

nHOU BRANCH TO CURRENT LINE + 1 TO CONTINUE EXECUTION 
+ULC+1 
RESUME AT LINE 5 

^FUNCTION HAS FINISHED EXECUTION 
aAND LOCAL UERROR IS GONE 
aCHECK GLOBAL VALUE OF UERROR 
UERROR 
11 VALUE ERROR 

C+A nADD WO UNDEFINED VARIABLES 
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Note that if an error occurs during an i execute, D ERROR contains six lines of 
text. For example: 

i 'QBREAK V 
7 9 i SYSTEM FUNCTION ILLEGAL IN EXECUTE 
WREAK 1 

A 

25 EXECUTE ERROR 
± < QBREAK V 

A 

QERROR 
7 9 i SYSTEM FUNCTION ILLEGAL IN EXECUTE 
QBREAK 1 

A 

25 EXECUTE ERROR 
1 'QBREAK V 

A 

Note that D ERROR is set by DFX, UASS, and DXQ, even though no message is 
displayed when the error occurs. 

The value of D ERROR is saved when you save the active workspace and can be 
localized within user-defined operations. (See the VAX APL User's Guide.) The 
default value is ' ' . 

Possible Errors Generated 



9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 
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□ EX Erasing a Named Object 
Type 



Form 



Monadic System Function 



erased / not-erased *■ QEX name-list 



Argument Domain 



TVpe 


Character 


Shape 


Matrix domain 


Depth 


1 (simple) 


uornain 

Type 


Boolean 


Rank 


l 


Shape 


p name-list 


Depth 


l (simple) 



Description 

QEX erases the local APL objects named by the rows of its argument. You 
cannot erase a named object that refers to a label, a group (a group name is 
always global), or to a suspended or pendent operation. 

The result of the Q EX system function is a Boolean vector that indicates which 
objects were erased: a 1 signifies that the object now has no value; a signifies 
that the object cannot be erased. Note that D EX returns if you specify an 
ill-formed identifier. 
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For example: 

)FNS 
ABCD GROW TEST 
)SI 

TESTL21 * 

A+3 kp'ABCDTESTGROU' 

A 
ABCD 
TEST 
GROW 

OEX A 
1 1 

)FNS 
TEST 

If the argument to D EX is empty, the result also is empty. 

Note that the memory allocated from VMS remains allocated even if you 
expunge an object from the workspace. If you want to release this memory, 
follow the sequence of steps discussed in the section on space considerations in 
Chapter 3 of the VAX APL User's Guide. 

Possible Errors Generated 



9 RANK ERROR (NOT MATRIX DOMAIN) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 
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□ EXP Expansion 



Type 




Dyadic System 


Function 


Form 




A D EXP B 


A OEXPUC] B 


Left Argument Domain 


Array 


Simple, homogeneous 


"type 


Near-Boolean 


Shape 


Vector domain 


Depth 


or 1 (simple) 


Right Argument Domain 


TVpe 


Any 


Shape 


Any 


Depth 


Any 


Result Domain 




Type 


Same as argument 


Rank 


ITppB 


Shape 


(K-l) +pB) , (p ,A) ,K\pB (for DIO=l) 


Depth 


lT^B 


Implicit Arguments 




None. 
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Description 

EXP builds an array by combining the items of an existing array with fill 
items. 

DEXP works the same as the expansion derived function. The examples 
shown for the Expansion operator in Chapter la also apply to Q EXP (you can 
substitute DEXP for the backslash (\ ) operator). The difference between UEXP 
and the backslash operator is that you can use D EXP as an operand to an 
operator. Operators cannot be used as operands to operators. D EXP applies 
along the last axis of B unless modified by an explicit axis (if ) in brackets. 
The shape of the result is the same as the original array B except along the 
applicable axis (p B [if] ) where the shape becomes the length of A (p , A). 

The following examples show UEXP with the each (") operator. Although 
the variables A and C are nested in the examples, they conform to the left 
argument domain requirement that specifies a simple array. This is because 
the each operator reduces the nesting by one level. 

Q«-i4<-(l 1 1) (1 1 1) 
+ + + + 

1 1 o ii| |i l o i| 
+ + + + 

D+B^(2 3pi6) (H 3q'ABCDEFGHIJKL<) 

+• + + + 

| 1 2 3 | \ABC\ 
it5 6| |MF I 

+ + \GHI\ 

\JKL\ 

+ + 

^ATTEMPT TO USE OPERATOR AS ARG TO " 
A\"B rAPL EVALUATES AS [A\)"B 

15 DOMAIN ERROR (ENCLOSED/HETEROGENEOUS ARRAY NOT ALLOWED) 
A\"B nAPL EVALUATES AS (A\)"B 

A 

A DEXP" B 

+ + + + 

1 1 2 3 1 \AB C\ 
|t 5 6 | \DE F\ 

+ + \GH I\ 

\JK L\ 

+ + 

A QEXP[2]"B nEXPAND ITEMS OF B USING THE ITEMS OF A 

+ + + + 

| 1 2 3 j \AB C\ 

1 4 5 6 | \DE F\ 
+ + \GH I\ 

\JK L\ 
+ + 
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□ <-0(l 1) (1 1 1 1) 

+ + + + 

|1 1| |1 1 1 1| 

+ + + + 

C QEXPllY'B fiUSE UEXP WITH AXIS ARGUMENT 

+ + + + 

|1 2 3| IASCI 
10 | \DEF\ 
K 5 6|| | 

+ + \GHI\ 

\JKL\ 
+ + 

Possible Errors Generated 



9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR 
15 DOMAIN ERROR 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 

2 8 AXIS RANK ERROR (NOT VECTOR DOMAIN) 

29 AXIS LENGTH ERROR (NOT SINGLETON) 

3 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 

30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 
30 AXIS DOMAIN ERROR (INCORRECT TYPE) 

30 AXIS DOMAIN ERROR (NOT AN INTEGER) 

30 AXIS DOMAIN ERROR (RIGHT ARGUMENT HAS WRONG RANK) 

3 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) 
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□ FI Converting Characters to Numerics 
Type 



Monadic System Function 



Form 



numeric-values «- Q FI numeric-character-string 

Argument Domain 



Type 


Character 


Shape 


Vector domain 


Depth 


or l (simple) 


L/lHIIdlll 

Type 


Numeric 


Rank 


l 


Shape 


Vector 


Depth 


l (simple) 



Implicit Arguments 

D NG (determines minus sign placement) 

Description 

D FI converts a numeric character argument to a vector of numeric values, 
placing a o in each position that does not correspond to a valid number. The 
shape of the argument must be in the vector domain. If the argument is empty, 
D FI returns an empty numeric vector. 

D FI separates the argument into fields that are delimited by one or more 
spaces, tabs, or a carriage return (optionally followed by a line feed); converts 
each field that contains a valid number; and inserts a to replace each field 
containing an invalid number. For example: 



2-88 APL Reference Manual 



System Variables and Functions 

D F I Converting Characters to Numerics 

A-^UFI '12 55e ~H C 2951 8 +5' 
_A 
12 "4 2951 8 

QA 
1 

Note that a plus sign preceding a number is not part of the number but is 
rather an operation to be performed on the number. However, in APL, the 
negative sign in the expression ~ 5 is a valid part of the number. 

D FI is often used in conjunction with Q VI and the compression derived 
function (see the Section 1.3.2 section) to select the valid numbers from a 
character string: D VI produces the left argument of the compression function, 
and D FI produces the right argument. For example: 

V Z+ AVERAGE 
[1] Q+'ENTER A LIST OF NUMBERS' o Z<-,Q 

[2] Z^(UVI Z)/UFI Z 

[3] Z*(+/Z)ipZ 

[4] V 

AVERAGE 
ENTER A LIST OF NUMBERS 
13. 540 +2 ".56. . 
2 

In the previous example, Q VI of Z equals 11010110 and OF I of Z equals 

13.5008" .560 

Recognition of negative numbers in the Q FI argument depends upon the value 
of the system variable ONG. If ONG equals 1 (the default), negative numbers in 
the OF I argument must begin with the high minus sign (~ ) to be recognized. 
If ONG equals 0, numbers preceded by a minus sign (- ) are recognized as 
negative numbers. If Q NG equals 2, negative numbers are preceded by an APL 
"+" symbol. (APL "+" prints as an ASCII "-" so that □ NG*- 2 can be used to 
handle negative numbers in strings that are read or written in ASCII.) For 
example: 

DffOl n~ MEANS NEGATIVE 

*<-'66 G ~7 +9 ~4' 
_DFJ X 
66 7 4 

QNG*-0 p- MEANS NEGATIVE 

UFI X 
66 

D/F02 R+ MEANS NEGATIVE 

UFI X 
66 +9 
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Note that when Q NG is , it may be useful for you to use APL to interpret data 
created by other languages, specifically those that do not use the high minus 
sign. 

Possible Errors Generated 



9 RANK ERROR (NOT MATRIX DOMAIN) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 
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D FLS Returning File Information 
Type 



Monadic System Function (query) 



Form 



file-info *■ 


UFLS charts 


Argument Domain 




Type 




Near-integer 


Shape 




Vector domain 


Depth 




or l (simple) 


Value 




"999 to 999 (but not ) 



Result Domain 



Type 


Integer 


Rank 


1 or 2 


Shape 


Vector or matrix (n by 5 ) 


Depth 


l (simple) 


Description 





UFLS returns information about files. The absolute values of charts represent 
the channels associated with the files you want to specify. The result contains 
one row of five values for each channel specified in the argument. The 
meanings of the values differ according to each file's organization. 

The values returned by D FLS have the following meanings (from left to right): 

First value Share bit: 1 means that you specified / SHARE in the 

argument for the associated DASS function; means 
that you did not. 
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Second value 



Third value 

Fourth value 
Fifth value 



For sequential files, the second value is the number of 
records read or written since the file was opened. For 
direct-access and relative files, it is the value of the 
last record or component number used for a successful 
read or write operation. For keyed files, it is the value 
of the last key of reference used for a successful read, 
write, or rewind. 

The maximum record length of the file (0 means there 
is no user limit on record size). 

The /BLOCKSIZE setting for the file. 

The type of the most recent I/O operation 



Value 
Returned 



I/O Operation 






None 


1 


Sequential read 


2 


Random read 


3 


Sequential write 


4 


Random write 


5 


Sequential delete 


6 


Random delete 



OFLS is described in the VAXAPL User's Guide along with other file I/O 
information. 

Possible Errors Generated 



9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (NOT AN INTEGER) 

15 DOMAIN ERROR (INVALID CHANNEL NUMBER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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□ FMT The Report Formatter 
Type 

Dyadic System Function 

Form 

report «- format-phrases UFMT {array I (array ; array;...)] 

Left Argument Domain 



Type 


Character 


Shape 


Vector domain 


Depth 


l (simple) 


Right Argument 


Domain 


Type 


Any 


Shape 


Any 


Depth 


< 2 (vector of arrays or a simple array) 


Result Domain 




Type 


Character 


Rank 


2 


Shape 


Matrix 


Depth 


l (simple) 



Implicit Arguments 

QNG (determines minus sign placement) 

Description 

UFMT combines the data from all the arrays in the right argument and 
arranges it as a single character matrix whose columns are then formatted 
according to corresponding format phrases specified in the left argument. The 
arrays in the right argument can be both character and numeric data. 
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D FMT can edit the data as it is moved to an output field. For example, D FMT 
fills or erases zeros in numeric fields; round numeric data; and inserts commas, 
dollar signs, and other text where appropriate. 

The right argument is a list of arrays of any type or rank. The list must be 
surrounded by parentheses (unless there is only one array in the list), and the 
arrays must be separated by semicolons. Alternatively, the right argument 
may be a single nested vector of simple arrays, which are treated in the same 
manner as a semicolon list. 

The left argument is a character vector comprised of one or more format 
phrases of the form described in Chapter 4 of the VAX APL User's Guide. The 
phrases must be separated by commas. 

The following table summarizes the syntax of the format phrase in the left 
argument. Note that rep (repetitions) refers to the number of consecutive 
target columns to be affected by the format phrase; quals refers to one of 
the qualifiers or decorators described in the following table; width refers to 
the width in the result array of a value from a column of data in the right 
argument; dig (digits) refers to the number of decimal places included in the 
result array; and col (column) refers to either the leftmost column that a value 
is to occupy in the result array (for type T), or the number of columns to be 
shifted before the next value is output to the result array. 



Phrase 



Type of Data 



flre/jj frqualsj A width 
h~epj IqualsJ E width.dig 
frrepj frqualsj F width.dig 
[[rep]] frqualsj G p patterns 
flrepl frqualsj I width 
llrepj R_qualsJ Y width 
IrepJ T IcolJ 
Irepl X Icoll 
flrepjpi textn 



Character 

Floating-point with exponent 

Fixed-point 

Picture 

Integer 

Byte 

Absolute tab 

Relative tab 

Literal 
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The following table summarizes the qualifiers and decorators used in the 
format phrase: 



Qualifiers 



Meaning 



B 



L 
Kn 

Sh symbol pairs p 

Wn 

Z 

Decorator 



For types I, E, F, G, and Y, if the value of the item in 

the target column is zero, make the field in the target 

column blank in the result array. 

For types I and F, insert commas between each group 

of three digits in the integer part of the formatted 

value. 

For types I, F, E, A, and Y, left-justify the fields in the 
target column. 

For types I, F, G, and E, before formatting the fields 
in the target column, multiply the fields by the scale 
factor io*re. 

For types I, E, F, G, and Y, replace, in the formatted 
output, all occurrences of the first character in each 
symbol pair with the corresponding second character 
of the symbol pair. 

For type E, use n exponent digits in the formatted 

output. 

For types I, F, and Y, fill leading blanks in the 

formatted output with zeros. 

Meaning 



Ma text ft 

Nr text 9, 
Or text a 
Pa text a 



For types I, F, and G, replace the sign of negative- 
formatted values with text placed to the left of the 
value. 

For types I, F, and G, place text to the right of 
negative-formatted values. 

For types I, F, G, and Y, replace formatted zero values 
with text. 

For types I, F, and G, place text to the left of positive- 
formatted values. 
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Decorator Meaning 



Qfl text a For types I, F, and G, place text to the right of 

positive-formatted values. 

Rb text a For types I, F, E, A, G, and Y, fill unused columns in 

the formatted output with text. 

Note that the delimiting pair p q may also be any of the following pairs: 

□ n "" dd <> <==> 

DFMT is also described in Chapter 4 of the VAX APL User's Guide. 

Possible Errors Generated 

9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR 

14 DEPTH ERROR 

15 DOMAIN ERROR (DUPLICATE FMT QUALIFIER) 

15 DOMAIN ERROR (DUPLICATE FMT STANDARD SUBSTITUTION CHARACTER) 

15 DOMAIN ERROR (EMPTY FMT STRING PARAMETER NOT ALLOWED) 

15 DOMAIN ERROR (ENCLOSED ARRAY IS NOT ALLOWED) 

2 7 LIMIT ERROR (FLOATING OVERFLOW) 

15 DOMAIN ERROR (FMT DECORATION OR LITERAL STRING TOO LONG) 

15 DOMAIN ERROR (FMT RIGHT ARGUMENT DOES NOT MATCH FORMAT PHRASE) 

15 DOMAIN ERROR (ILL FORMED FMT PARAMETER) 

15 DOMAIN ERROR (ILLEGAL CHARACTER IN FMT LEFT ARGUMENT) 

15 DOMAIN ERROR (ILLEGAL FMT FORMAT PHRASE) 

15 DOMAIN ERROR (ILLEGAL FMT G FORMAT PHRASE PATTERN CHARCTER) 

15 DOMAIN ERROR (ILLEGAL FMT LITERAL STRING DELIMITER) 
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15 DOMAIN ERROR ( ILLEGAL FMT S QUALIFIER SYMBOL ) 

15 DOMAIN ERROR (ILLEGAL USE OF FMT QUALIFIER) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (MISSING FMT FORMAT PHRASE SEPARATOR) 

15 DOMAIN ERROR (MISSING FMT FORMAT PHRASE/ QUALIFIER) 

15 DOMAIN ERROR (MISSING LITERAL STRING IN FMT LEFT ARGUMENT) 

15 DOMAIN ERROR (NO DIGIT SELECTOR IN FMT G FORMAT PHRASE PATTERN) 

15 DOMAIN ERROR (NO FMT EDITING FORMAT PHRASE) 

15 DOMAIN ERROR ( PARAMETER OUT OF RANGE) 

15 DOMAIN ERROR (RIGHT ARG TOO DEEPLY NESTED) 

15 DOMAIN ERROR ( UNBALANCED TEXT DELIMITER IN FMT LEFT ARGUMENT) 

15 DOMAIN ERROR ( UNBALANCED PARENS IN FMT LEFT ARGUMENT) 

15 DOMAIN ERROR ( UNPAIRED SYMBOL IN FMT S QUALIFIER) 
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D FX Establishing an Operation 
Type 

Monadic System Function 

Form 

operation-name^ FX operation-definition 

Argument Domain 



"type 


Character 


Shape 


Matrix domain 


Depth 


l (simple) 


L/unidin 

Type 


Character (Numeric if error is detected) 


Rank 


or l 


Shape 


Vector (Scalar if error is detected) 


Depth 


or l (simple) 



Implicit Arguments 

D 10 (controls origin of line number in error) 

Description 

D FX reverses the operation of the Q CR system function; that is, it creates in 
internal form the operation defined by its argument. 

The argument is assumed to be a character matrix that contains the canonical 
representation of an operation. The shape of the argument must be in the 
matrix domain. Blank lines in the argument are removed in the operation 
established by D FX. 

□ FX fails if the operation's name is the same as that of an existing label, 
variable, or group, or if it is the same as that of an existing operation that is 
pendent or suspended. If an operation already exists in your workspace with 
the same name, D FX replaces it and removes any trace, stop, or monitor bits 
that were set on it. 
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The □ FX function executes properly if the matrix it references is identical to 
a canonical representation. If □ FX fails, APL returns a scalar index (which is 
DIO-sensitive) representing the row in the matrix where the error occurred, 
and no change is made to any operation or array in your workspace. You can 
check the value of D ERROR for a description of what was wrong with the line in 
error. 

If D FX is successful, its result is a character vector containing the name of the 
operation defined. If the argument is empty, the result is empty. 

The following example begins where the D CR example from the □ CR section 
ended. Here, the plus sign in SHOWCRFX is changed to a multiplication sign; 
then, the Q FX system function is applied to SHOWCRFX to replace the function 
MEAN with its new version: 

SHOWCRFXl3;6]<-<x< 

UFX SHOWCRFX 
MEAN 

V MEANIU1V 

VMEANX+NSUBJ MEAN X 
[1] n SUM VECTOR X 
[2] SUMX+x/X 
[3] MEANX^SUMXiNSUBJ 

V 

X 
8 6 3 9 5 12 17 4 

10 MEAN X 
115152 

X+2 4p 'F X1234' 

I[l;2 3]«-DCm[14 11] ftEMBED CRLF IN OPERATION HEADER 

UFX X 
1 

OERROR 
5 DEFN ERROR [EXTRANEOUS CHARACTERS AFTER COMMAND) 
F 
X 



Possible Errors Generated 

9 RANK ERROR (NOT MATRIX DOMAIN) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR ( INCORRECT TYPE) 
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D GAG Preventing Interruptions 



Type 




System Variable (session) 


Form 




OGAG ■*- near-. 


integer-singleton 


integer-scalar 


-*- DGAG 


Value Domain 




Type 


Integer 


Shape 


Singleton 


Depth 


o or l (simple) 


Value 


o , l , 2 , or 3 


Default 


Determined when APL is invoked 



Result Domain 



Type 


Integer 


Rank 





Shape 


i (scalar) 


Depth 


(simple scalar) 


Description 





DGAG allows you to specify how APL handles messages that arrive at your 
terminal from other users. You can set GAG to the following values: 

Value Meaning 

Display messages 

1 Refuse messages 

2 Trap, translate, and display messages 

3 Signal BROADCAST RECEIVED 

Setting UGAG to is equivalent to executing the DCL command set terminal 
/broadcast, and setting DGAG to 1 has the same effect as the DCL command 
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set terminal/nobroadcast. When UGAG is 1, messages from nonprivileged users 
are suppressed (note that senders are not told that their messages were not 
received). For more details, see the VMS DCL Dictionary. When you return to 
DCL from APL, the original system value for UGAG is restored, unless the exit 
from APL was a panic exit; in that case, the setting established in the APL 
session remains in effect. 

Setting UGAG to 2 is equivalent to executing the DCL command SET 
TERMINAL/BROADCAST, with the addition of instructing APL to display 
the message in the character set that is currently set for the terminal. If you 
use an APL terminal, the default setting is 2 when APL is invoked. 

Setting UGAG to 3 allows you to trap messages with Q TRAP and to view them 
at a later time. As messages arrive at the terminal, APL signals BROADCAST 
RECEIVED followed by a secondary message of the broadcast text. 

The default setting of D GAG is the current monitor setting. Note that □ GAG is 
a session variable; that is, its value is not saved with the workspace, and □ GAG 
is not reset by the execution of a ) CLEAR command (see Chapter 3). D GAG can, 
however, be localized in user-defined operations. 

Possible Errors Generated 



9 RANK ERROR {NOT VECTOR DOMAIN) 

10 LENGTH ERROR {NOT SINGLETON) 

15 DOMAIN ERROR {ENCLOSED ARRAY NOT ALLOWED) 
15 DOMAIN ERROR {INCORRECT TYPE) 
15 DOMAIN ERROR {NOT AN INTEGER) 
2 7 LIMIT ERROR {INTEGER TOO LARGE) 
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D 10 Index Origin 

Type 

System Variable 

Form 



010 -s- near-integer-singleton 
integer-scalar-current-value -«- QJ0 



Value Domain 




Type 


Integer 


Shape 


Singleton 


Depth 


or l (simple) 


Value 


or l 


Default 


i 



Result Domain 



T>pe 


Integer 


Rank 





Shape 


i o (scalar) 


Depth 


o (simple scalar) 


Description 





D 10 specifies the setting of the index origin. This setting determines whether 
the values of an array are indexed beginning with position or 1. The default 
position is 1. 

D 10 also affects the operation of axis {[K ]), exceopt when axis is used with 
user-defined operations. In addition, Q 10 affects the operation of the following 
primitive and system functions: 

i A A\B ?A A?B &A fA A§B 00MB OFX B 

The value of D 10 is saved when you save the active workspace and can be 
localized in user-defined operations. 
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Examples: 

□I0<-1 

1 3 
1 2 3 

A<-2 4p i 6 

+ /[2]4 
10 1H 

+ /LHA 
8 1- 6 

+/101A 
30 jIZIS DOMiltf ERROR (AXIS LESS THAN INDEX ORIGIN) 

+/L01A 

A 

DJO^o 

i3 
12 

+ /[2]4 
30 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 
+ /L21A 

A 

+ /U1A 

io in 

+/10M 

6 8 H 6 

DI0+7 
15 D0M4Itf EtfflOi? (SYSTEM VARIABLE VALUE MAY ONLY BE OR 1) 
□IO<-7 



Possible Errors Generated 

9 i^/MT ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (NOT SINGLETON) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

15 DOMAIN ERROR (SYSTEM VARIABLE VALUE MAY ONLY BE OR 1) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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D L Monitoring Variable Changes 
Type 

System Variable 

Form 

UL +■ any -value 
variable-name^ DL 

Value Domain 



Type 


Any 


Shape 


Any 


Depth 


Any 



Result Domain 



Type Character (any when set by user) 

Rank l (any when set by user) 

Shape Vector (any when set by user) 

Depth l (simple) (any when set by user) 

Default i o 



Description 



DL and OR are system variables that are implicitly used by WATCH. (DL is set 
implicitly by the system when a variable changes, but can also be set by the 
user.) D WATCH is a system function that is used to monitor any changes in one 
or more variables. When a change occurs in a monitored variable, APL assigns 
information to D£ and OR: DL contains a character vector showing the name of 
the variable that has changed; Q R contains the previous value of the changed 
variable. APL assigns this information regardless of whether monitoring is set 
for signal or display mode. 

The default value for both QZ and QR is i o . Immediately after a □ WATCH event 
occurs, D L and □ R contain the new information that results from the event. 
However, this information may change as an operation continues execution 
(this is especially true if an error occurs during an assignment or reference of a 
variable that is associated with a watchpoint). 
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Both QL and OR can be localized, explicitly assigned values of any type, and 
saved in the workspace. 

Note that you cannot include Q L or Q R in the right argument to dyadic 

WATCH. 

Possible Errors Generated 

None. 
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D L C Line Counter 
Type 

Niladic System Function 

Form 

current-line-number +■ Q L C 

Result Domain 



Type 


Integer 


Rank 


l 


Shape 


Vector 


Depth 


l (simple) 


Default 


Empty 


Description 





D L C (line counter) allows you to obtain a partial report on operations that 
are currently being executed. The function returns a vector of all the line 
numbers contained in the state indicator; the numbers are arranged as they 
would appear in the )SI system command display (see Chapter 3.) If the state 
indicator is empty, ULC returns an empty numeric vector. 

The ULC system function is particularly useful in restarting suspended 
operations. For more information, see the VAX APL User's Guide. For 
example: 

VNEU 

[1] +1 V 

NEW aCALL FUNCTION, THEN SEND ATTENTION SIGNAL 
18 ATTENTION SIGNALED 
NEW[11 +1 

A 
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Possible Errors Generated 

None. 
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□ LX Latent Expression 
Type 



System Variable 




Form 




QLX *• character-vector 


current-value +■ 


QLX 


Value Domain 




Type 


Character 


Shape 


Vector domain 


Depth 


or l (simple) 


Default 


i i 



Result Domain 



Type 


Character 


Rank 


l 


Shape 


Vector 


Depth 


1 (simple) 


Description 





D LX specifies an APL expression that is executed automatically when the 
workspace is loaded. 

The value you assign to D LX must be a character vector. The default value is 
' ' . APL processes the expression as if you had specified ± QLX. Any error 
messages you receive are produced by the execute function. 

The QLX system variable is useful in restarting a suspended operation. For 
example: 

QLX«-<-+QLC 

LX is also useful for invoking a particular user-defined operation (see the 
VAX APL User's Guide) when you load the workspace. For example: 

OLX+< STARTUP' 
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The D LX system variable is often used to display a message when the 
workspace in which it is denned is loaded. For example: 

ULX+' ' 'NOTE NEW LINE PRINTER IN OPERATION' ' ' 

)SAVE MYUS 
FRIDAY 16-NOV-1990 10:09:27:02 7 ELKS 

) CLEAR 
CLEAR WS 

)L0AD MI US 
SAVED FRIDAY 10-ff07-1990 10:09:27.02 7 ELKS 
NOTE NEU LINE PRINTER IN OPERATION 

When you want to load a workspace without invoking Q LX, you can use the 
)XLOAD command (see Chapter 3) if you are the owner of the workspace. 

APL executes Q LX only in immediate mode and only when the state indicator 
stack is either empty or has a suspended operation on top. If the top of the 
stack contains a Q input function, the latent expression is executed only after 
the pendent D input is removed from the stack. The latent expression is not 
executed if the top of the stack contains an execute function, or if the loaded 
workspace is in function-definition mode. For example: 

)L0AD MYWS 
SAVED THURSDAY 8-NOV-1990 19:42:58.52 15 BLKS 

V F 
[1] A + l 

[2] X*UXQ')SAVE MYWS' 
[3] <X IS ' ;X 
[4] 'END OF F' V 

F 
X IS THURSDAY 8-TO7-1990 17:01:59.54 16 BLKS 
END OF F 

) CLEAR 
CLEAR US 

)L0AD MYUS 
X IS SAVED THURSDAY 8-ffOF-1990 17:01:59.54 15 BLKS 
END OF F 

In this example, the note about the new line printer is not displayed when the 
workspace is loaded because the workspace was saved during the execution of 
an QXQ system function; thus, the QXQ function is at the top of the stack when 
the workspace is reloaded, and APL completes the Q XQ function rather than 
executing the latent expression. 
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If you were to save the workspace after execution of the function F completed, 
the latent expression would be executed the next time the workspace was 
loaded: 

)SAVE MYWS 
FRIDAY 16-TO7-1990 10:1+3:59.54 8 BLKS 

) CLEAR 
CLEAR WS 

)L0AD MYWS 
SAVED FRIDAY 16-ff07-1990 10:43:59.54 8 BLKS 
NOTE NEW LINE PRINTER IN OPERATION 

Note that when the function F was executed, the value of X displayed by 
operation line [3] was equivalent to the message displayed by the ) SA VE 
system command: 

X IS MONDAY 27-SEP-1982 18:07:42.02 8 BLKS 

However, when the execution of function F was resumed because the saved 
workspace was loaded by a )LOAD command, the value of X displayed by 
operation line [3] was equivalent to the message displayed by the )LOAD 
command: 

X IS SAVED MONDAY 27-S£T-1982 18:07:42.02 8 BLKS 

Thus, as shown by this example, it is possible to determine whether the 
workspace has just been saved or has just been loaded. 

The value of Q LX is saved when you save the active workspace and can be 
localized in user-defined operations. 

Possible Errors Generated 



9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (.ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 
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Q MAP Defining External Routines to APL 
Type 

System Function 

Form 

external-routine-definition +- D MA P function-name 
function-name *- function-header UMAP image-definition 



Monadic Argument Domain 



Type 


Character 


Shape 


Vector domain 


Depth 


or l (simple) 


Dyadic Left Argument Domain 


Type 


Character 


Shape 


Vector domain 


Depth 


or l (simple) 


Dyadic Right Argument Domain 


Type 


Character 


Shape 


Vector domain 


Depth 


or l (simple) 


Result Domain 




Type 


Character 


Rank 


l 


Shape 


Vector 


Depth 


l (simple) 
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Parameters 

external-routine-definition 

The operation header returned by the monadic form of UMAP. This is the 
same header that dyadic UMAP uses when you successfully define the external 
routine to APL. 

function-name 

Specifies the name of the external routine. For dyadic UMAP, if both function- 
header and image-definition are empty, and are in the vector domain, then 
the result is an empty vector. For monadic UMAP, if function-name is empty, 
the result is an empty character vector. If the value of function-name does 
not name an external routine, APL signals DOMAIN ERROR {NOT AN EXTERNAL 
FUNCTION). 

function-header 

Describes the external routine, function-header has the following form: 

\result/att+ fl entry-point farg 1 /att farg2/atq ... J 

result I att specifies that the external function returns a result. Note that the 
result must be a scalar. (If you want to return data that has a rank greater 
than 0, you can modify a formal parameter with the external routine.) The 
I att qualifier specifies the type of the result. It has the form / TYPE : vms-data- 
type, and must be one of the external data types in the Table 2-7 (excluding 
/TYPE-.Z). 

Do not specify the /MECHANISM attribute for the result of an external routine; 
APL determines the mechanism by the value specified for / TYPE. Table 2-7 
describes these default mechanisms. 

If the result type occupies 8 bytes or less, APL assumes the mechanism is 
IMMEDIATE. If the result type occupies more than 8 bytes, APL assumes the 
mechanism is DESCRIPTOR for strings and REFERENCE for all others, entry- 
point is the name that you want APL to associate with the shared image 
entry point specified in image -definition. After you define entry-point, you 
can call the external routine as if it were a user-defined operation. Note that 
entry-point has a name class value of 3. 

Dyadic UMAP signals DOMAIN ERROR (NAME IN USE) if entry -point is the same 
name as an existing label, variable, or group, or if it is the same name as an 
existing operation that is pendent or suspended. If an operation already exists 
in your workspace with the same name, and it is not pendent or suspended, 
UMAP replaces it. 
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argn specifies the names of the function's formal parameters. These names 
are similar to the dummy arguments of a user-defined operation; they are 
placeholders only, and you specify the actual values for these parameters when 
you invoke the function. 

The maximum number of formal parameters you can specify is 255 (including 
result). The names must be valid APL identifiers; they do not have to be 
unique. An external function can only be monadic or niladic; all of the formal 
parameters belong to the function's right argument, latt determines the 
attributes for each of the formal parameters and for the external routine's 
result. For parameters, the attributes specify the kind of access that the 
external routine has to the parameter (either read, write, or both), the data 
type of the parameter, and the passing mechanism used to send the parameter 
between APL and the external routine. Valid qualifiers for latt include 
/ACCESS, /TYPE and /MECHANISM, 

image-definition 

The name of a shared image (in the form of a VMS file name or logical name) 
and its entry point. If you use a logical name you cannot change the name once 
the shared image is mapped by APL. image-definition has the following form: 

{vms-filename I vms-logical-name} [{/ entry | /value} lisymbolft} 

vms-filename or vms-logical-name specifies the name of the VMS shared 
image. If you do not use a logical name, you can only specify a file name, 
not a complete file specification. The default directory for vms-filename is 
SYS$SHARE:, and the default file type is .EXE. If you use vms-logical-name, 
you should not redefine the logical name to point to a different file once the 
shared image is mapped. 

Note that you can use the equal sign delimiter (=) in place of the colon (:). 
Spaces are allowed before and after the /ENTRY or /VALUE qualifier, the 
delimiter, and the value for symbol. 



Qualifiers 



/ENTRYfzsymbol^ 

Used with dyadic DMAP, specifies the name of the entry point in the shared 
image. An entry point is the starting address of executable code. If you 
do not specify /ENTRY, or if you specify /ENTRY with no value for symbol, 
APL assumes that the name of the entry point is the same as the value for 
function-name. 
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/VALUEl:symbol$ 

Used with dyadic DMAP, specifies the name of a global constant in the shared 
image. A global constant is a 32-bit signed longword value. When you specify 
/VALUE, then function-header must specify a niladic function that returns 
a value with a return type of L (for example, ' Z/TYP : L+- F ' ). If / VALUE is 
specified when there is no value for symbol, APL assumes that the name of the 
global constant is the same as the value for function-name. 

/ACCESS 

Specifies whether the parameter is read only or modifiable. The value IN 

indicates that the external routine reads the parameter and does not modify 

its value. The value IN OUT indicates that the routine reads the parameter and 

may modify it. The value OUT indicates that the routine writes a value to the 

parameter. 

When you specify INOUT or OUT, the actual parameter that you specify when 
you invoke the function must be a character string that names the variable 
that the routine will read (in the case of INOUT) and write. If the variable does 
not have a value when you call the external routine, APL assumes the variable 
is a scalar and will accept a scalar only when the value is returned. 

If you do not specify a value for /ACCESS, APL uses the IN value as the 
default. You cannot specify the /ACCESS attribute for the result of an external 
routine; by definition the access is always OUT. 

Note that you can abbreviate the values for /ACCESS to their shortest unique 
prefixes. 

/TYPE 

Specifies the attribute for both the formal parameters and the result (if any). 
It is one of the external types shown in Table 6-1 in the VAX APL User's Guide. 
On a formal parameter, /TYPE specifies the VAX data type that the external 
routine is expecting. On the result, /TYPE specifies the VAX data type that 
will be returned. Data internal to APL has one of the following types: 

• Character data in the APL character set (8-bits per value) 

• Boolean data, a subset of numeric data (1-bit per value) 

• Integer data, a subset of numeric data (32-bits, signed, per value) 

• Floating-point, a subset of numeric data (64-bits, D_floating, per value) 

Because VMS supports many more data types than APL, conversions will take 
place as data leaves and returns to APL from the external routine. Tables 6-2 
and 6-3 in the VAX APL User's Guide summarize these possible conversions. 
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The default data type is /TYPE-.Z (unspecified), which indicates that data is 
passed out of the workspace without conversion. Data that is passed out of 
APL as /TYPE: Z cannot return to APL; for this reason, a formal parameter 
with the attribute /TYPE: Z must also have the attribute /ACCESS-.IN. 

Note that you cannot abbreviate any of the values to the /TYPE qualifier. 
Table 2-7 Characteristics of External Data Types 



External 


Type 


DEFAULT result 


Length 


Type 


Name 


/MECHANISM 


in Bytes 


Z 


Unspecified 


N/S 




BU 


Byte Logical 


IMM 


1 


wu 


Word Logical 


IMM 


2 


LU 


Longword Logical 


IMM 


4 


QU 


Quadword Logical 


N/S 




OU 


Octaword Logical 


N/S 




B 


Byte Integer 


IMM 


1 


W 


Word Integer 


IMM 


2 


L 


Longword Integer 


IMM . 


4 


Q 


Quadword Integer 


N/S 




O 


Octaword Integer 


N/S 




F 


F_floating 


IMM 


4 


D 


D_floating 


IMM 


8 


G 


G„floating 


IMM 


8 


H 


H_floating 


REF 


16 


FC 


F complex 


IMM 


8 


DC 


D complex 


REF 


16 


GC 


G complex 


REF 


16 


HC 


H complex 


REF 


32 



Key to Default result /MECHANISM 

N/S — not supported 
IMM — by value 
REF — by reference 
DES — by description 



(continued on next page) 
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Table 2-7 (Cont.) Characteristics of External Data Types 



External Type 


DEFAULT result 


Length 


Type 


Name 


/MECHANISM 


in Bytes 


CIT 


COBOL Temp 


N/S 




T 


8-bit Text 


DES 


1 


VT 


Varying Text 


REF 


1 


NU 


Numeric String 


DES 


1 


NL 


Left Sign String 


DES 


1 


NLO 


Left Overpunch 
String 


DES 


1 


NR 


Right Sign String 


DES 


1 


NRO 


Right Overpunch 

String 


DES 


1 


NZ 


Zoned Sign String 


DES 


1 


P 


Packed Decimal 


N/S 




V 


Bit 


IMM 


1 


vu 


Bit Unaligned 


N/S 




ZI 


Instructions 


N/S 




ZEM 


Entry Mask 


N/S 




DSC 


Descriptor 


N/S 




BPV 


Bound Procedure 


N/S 




BLV 


Bound Label 


N/S 




ADT 


Date/Time 


N/S 




other 


DEC or user reserved 


N/S 




Key to Default result /MECHANISM 






N/S— 
IMM- 
REF- 
DES- 


-not supported 
—by value 
-by reference 
-by description 







/MECHANISM 

Specifies one of the three techniques for passing formal parameters from APL 
to the external routine. These techniques are IMMEDIATE, REFERENCE, and 
DESCRIPTOR. IMMEDIATE specifies that the value of the parameter is the value 
you want to pass. REFERENCE specifies that the value of the parameter is the 
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address of the value you want to pass. DESCRIPTOR specifies that the value 
is the address of a descriptor that contains the address and length of the data 
as well as other attributes (if the descriptor requires them). Note that the 
descriptor length field contains the length of the object. 

If you do not specify the /MECHANISM attribute when you invoke 
dyadic UMAP, APL uses a default when you call the external routine. 
If the parameter is /TYPE: Z, APL assumes /MECHANISM -.REFERENCE. 
Otherwise, the default is based on the rank of the actual argument being 
passed: /MECHANISM: REFERENCE is chosen for scalars and vectors, and 
/MECHANISM -.DESCRIPTOR is used for arrays of rank 2 or higher. 

When you specify /MECHANISM: IMMEDIATE, the formal parameter must be 
a scalar; if the internal length of the actual value that you specify when you 
invoke the external function is greater than 4 bytes, APL signals LENGTH 
ERROR. 

When you specify /MECHANISM -.DESCRIPTOR, APL uses string descriptors 
(CLASS_S) for the vector domain, and array descriptors (CLASS_A with a 
multipliers block) for arrays of rank 2 or greater. (The type of the value being 
passed does not affect the choice of descriptor.) For more information on 
descriptors, see the Introduction to VMS System Routines. 

Note that you can abbreviate the values for /MECHANISM to their shortest 
unique prefixes. 



Description 



Dyadic UMAP defines an external routine to APL. Once a routine is defined in 
a workspace, the workspace can be saved, loaded, or copied, and the definition 
for the routine remains intact. 

The monadic UMAP system function returns an operation header that provides 
information on the current definition associated with an external routine. 
APL returns an operation header {external-routine-definition). This is the 
same header that dyadic UMAP uses when you successfully define the external 
routine to APL. The header's form is as follows: 

Iresult/att +-Jfunction-name/info fargl/att arg2/att ...] 

function-name shows the name that APL currently associates with the external 
routine. 

I info shows the name and entry point of the shared image that contains the 
external routine. The shared image name is preceded by /IMAGE: , and the 
entry point name is preceded by /ENTRY : . If the external symbol defines a 
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global constant instead of an entry point, then the symbol name is preceded by 

/VALUE:. 

argn/att ... shows the names and attributes of the external routine's formal 
parameters. The attributes describe the settings for /ACCESS, /TYPE, and 
/MECHANISM that APL associates with each formal parameter. If you did not 
specify a value for any of the attributes when you defined the external routine, 
monadic QMAP reports the following default selections: /ACCESS: IN, /TYPE-.Z, 
and /MECHANISM -.UNSPECIFIED (APL does not choose a default mechanism 
until you call the external routine). 

result I att shows the name and attributes of the result that is returned by 
the external routine if there is one. the attributes describe the settings for 
the following: /TYPE, which you defined with dyadic UMAP; and /MECHANISM, 
which APL determines based on the value for /TYPE. Monadic UMAP does 
not report the /ACCESS attribute, which is assumed to be /ACCESS-.OUT by 
definition. 

If the routine does not return a result, then monadic UMAP does not report a 
value for result/ att. 

The result of monadic QMAP contains one blank before each formal parameter, 
and one blank following the +■ symbol (unless the function has no result). 

Both monadic and dyadic QMAP are described in Chapter 6 of the VAX APL 
User's Guide. 

Possible Errors Generated 

Dyadic Form 

9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (ILLEGAL EMPTY ARGUMENT) 

15 DOMAIN ERROR (ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (ERROR ACTIVATING IMAGE) 

15 DOMAIN ERROR (EXTRANEOUS CHARACTERS AFTER COMMAND) 

15 DOMAIN ERROR ( FUNCTION NAME MISSING) 

15 DOMAIN ERROR (ILL FORMED NAME) 

15 DOMAIN ERROR (INCORRECT TYPE) 



2-118 APL Reference Manual 



System Variables and Functions 

DMAP Defining External Routines to APL 



15 DOMAIN ERROR (INCORRECT PARAMETER) 

15 DOMAIN ERROR (INVALID FILE SPECIFICATION) 

15 DOMAIN ERROR (KEY NOT FOUND IN TREE) 

15 DOMAIN ERROR (NAME IN USE) 

15 DOMAIN ERROR (OPERATION SUSPENDED OR PENDENT) 

15 DOMAIN ERROR (WILDCARDS NOT ALLOWED IN FILE SPEC) 

2 7 LIMIT ERROR (ARGUMENT TOO LONG) 
Monadic Form 

9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (EXTRANEOUS CHARACTERS AFTER COMMAND) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN EXTERNAL FUNCTION) 
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D MBX Mailbox System Function 
Type 

System Function 

Form 

mailbox-info +• OMBX chans 

Argument Domain 



TVpe 


Near-integer 


Shape 


Vector domain 


Depth 


or l (simple) 


Value 


~ 9 9 9 through 9 9 9 (but not o ) 


Result Domain 




TVpe 


Integer 


Rank 


l or 2 


Shape 


Vector or matrix (n by 3 ) 


Depth 


l (simple) 


Description 





OMBX returns information on the status of mailboxes. For each channel 
specified, D MBX returns a row of three elements denoting (from left to right): 

• The physical device number assigned to the mailbox (or o if the mailbox is 
remote, and " l if the channel is not associated with a mailbox). 

• The Process IDentification number (PID, returned by □ UL) of the last user 
to receive a message you sent to the mailbox (or ~ l if no messages have 
been sent). 

• The PID of the last user from which you received a message in the mailbox 
(or ~ l if no messages have been received). 

The result is a matrix (or a vector if the argument is a singleton) with the 
shape n by 3, where n is the length of the argument. 
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To return a value for UMBX, APL must open the mailbox if it is not already 
open. (For a list of commands that open files, see the VAX APL User's Guide.) 
For channel numbers represented in the argument by positive integers, APL 
opens the mailbox for input; for channel numbers represented by negative 
integers, APL opens the mailbox for output. Note that whether a mailbox is 
opened for input or output is not significant, because APL treats mailboxes like 
terminals: it allows both input and output at the same time, even in sequential 
modes. 

UMBX is described in the VAX APL User's Guide along with other file I/O 
information. 

Possible Errors Generated 



9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (NOT AN INTEGER) 

15 DOMAIN ERROR (INVALID CHANNEL NUMBER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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□ MONITOR Gathering Data on Operations 
Type 



Form 



System Function 



success I failure +- line-numbers Q MONITOR operation-names 
monitor-database +- MONITOR operation-name 



Left Argument Domain 



Type 


Near-integer 


Shape 


Vector domain 


Depth 


o or l (simple) 


Right Argument Domain 


Type 


Character 


Rank 


l or 2 


Shape 


Matrix domain 


Depth 


or l (simple) 


Result Domain 




Type 


Integer (dyadic) or Boolean (monadic) 


Shape 


Vector or matrix (n by 3 ) 


Depth 


l (simple) 


Description 





D MONITOR is a debugging tool that allows you to gather statistics on an 
operation. These include the following: 

• The execution count, or the number of times an operation or operation line 
is invoked while OMONITOR is enabled. The possible range is to ~ 1 + 

2*31. 
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• The accumulated CPU time charged to an operation or operation line while 
D MONITOR is enabled. The possible range isoto~i + 2*3i milliseconds 
(about 24.5 days). 

If either of these statistics overflows its range, its value is reset to 0, and the 
data collection continues. 

Once QMONITOR is enabled, APL collects data from the moment the operation 
(or operation line) receives control to the moment it relinquishes control. APL 
increments the execution count each time the control is relinquished and 
registers the accumulated CPU time from the beginning moment to the ending 
moment. If the operation (or operation line) calls another operation, the result 
includes the time required to execute this second operation. 

You can view a monitored operation with the )EDIT command, but if you 
modify the operation with )EDIT, QFX, or QMAP, you will disable QMONITOR 
and lose any collected data. If you view the operation with the A editor, you 
can change the contents of individual lines without affecting the status of 
QMONITOR. Note that you cannot add or delete lines or modify the header of a 
monitored operation with the A editor. 

The dyadic form of QMONITOR enables and disables monitoring of an operation. 
The form used is as follows: 

success/failure ^line-numbers qmonitor operation-names 

The right argument identifies the user-defined operations you want to monitor. 
It belongs to the character matrix domain, and each row specifies one operation 
name. The operations must be user-defined, and they must be unlocked. You 
can also monitor line of external functions (this has the same meaning as 
monitoring line of a user-defined operation). When the same operation name 
applies to more than one operation in the workspace, APL monitors the most 
local one. 

The left argument identifies the lines you want to monitor. It belongs to 
the near-integer vector domain. The line numbers can be in any order. APL 
ignores negative line numbers, repeated line numbers, and line numbers that 
do not appear in the operation. If the left argument contains a 0, APL monitors 
the entire operation. 



APL Reference Manual 2-123 



System Variables and Functions 

U MONITOR Gathering Data on Operations 

The result of dyadic Q MONITOR is a Boolean vector. Each position in the vector 
corresponds to a row of the right argument. A 1 means that the attempt to 
enable D MONITOR was successful, and a means the attempt was unsuccessful. 
If the right argument is empty, the result is also empty. For example: 

PHASEONE *■ QBOX ' F00 
DOUBLE 
MOVE 
SPREAD 
FINAL ' 

(i50) OMONITOR PHASEONE a PARENTHESES REQUIRED 



To disable D MONITOR, use the dyadic form with an empty left argument, as 
follows: 

(i0) UM0NIT0R 'DESIGN' 
1 

MONITOR on an operation that is already being monitored, APL reinitializes 
any previously collected data. If you want to use this data before losing it, you 
must retrieve it with the monadic form of OMONITOR before you reset it with 
the dyadic form. 

monitor-database *■ omonitor operation-name 

The monadic form of OMONITOR queries for any collected data. The argument 
must be in the character matrix domain, and must have at most one row; you 
must query for OMONITOR information one operation at a time. Note that the 
operation must be unlocked and user-defined. 

Monadic OMONITOR returns an n by 3 numeric matrix, where n is the number 
of monitored lines. Each row of the matrix contains the current data for each 
line since OMONITOR was enabled. The result is formatted as follows: 

line-number execution-count cpu-time-in-milliseconds 

For example: 

OMONITOR 'F00' 

1 1 20 

2 5 104 

3 5 96 

H 1 20 
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The result is an empty by 3 matrix in the following five instances: 

• The right argument is empty 

• The right argument does not specify an operation name 

• The operation does not exist 

• The operation is locked 

• The operation is not being monitored 

Possible Errors Generated 

The Dyadic Form 

9 RANK ERROR (NOT MATRIX DOMAIN) 

9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
Monadic Form 

9 RANK ERROR (NOT MATRIX DOMAIN) 

10 LENGTH ERROR 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 
15 DOMAIN ERROR (INCORRECT TYPE) 
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□ NC Returning a Name Classification 
Type 



Form 



Monadic System Function 



name-class-list ■*- UNC name-list 



Argument Domain 



TVpe 


Character 


Shape 


Matrix domain 


Depth 


o or l (simple) 


Result Domain 




Type 


Integer 


Kank 


l 


Shape 


l + p name-list 


Depth 


l (simple) 



Description 

UNC responds with the name class of each APL object that you specify in the 
argument. APL objects include user-defined objects, system variables, and 
system functions. Each row of the argument must contain the name of one 
object. 

The result has a length equal to the number of rows in the argument. If the 
argument to D NC is empty, the result is i . 
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The possible name classes and values returned by UNC are as follows: 

DNC Name Classes and Values 
Value Name Class 

~ 2 Derived function 

~~ 5 Niladic system function 

~ 4 Group 

~ 3 Monadic, Dyadic, or Ambivalent system function 

- 2 System variable 

~ l Ill-formed identifier 

Name not in use 

1 Label 

2 Variable 

3 User-defined function 

1 User-defined operator 

Examples: 

)FNS 
AVER MEAN 

)VARS 
A B C TOT 

UNC 'AVER' 
3 

UNC 'C 
2 

QNC 'UNC 
"3 

_ UNC J Hq'A TOT UIO MEANB < 

2 2 2 1 
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Note that NC returns the current local rather than global name classification 
of the object. For example: 

pF is a function and a variable 

VF;F 
[1] F<-1 o QBREAK 'STOP F' V 

UNC 'F< fiTHIS QUERY RETURNS THAT F IS A FUNCTION 

3 

F nEIECUTE F, WHICH GETS SUSPENDED 

STOP F 

UNC ' F' fiNOM THE MOST LOCAL F IS A VARIABLE 

2 

Possible Errors Generated 

9 RANK ERROR (NOT MATRIX DOMAIN) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 
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D NG Print High Minus 
Type 

System Variable 

Form 

BNG *■ near-integer-singleton 
integer-scalar +• D NG 



Value Domain 




Type 


Near-Integer 


Shape 


Singleton 


Depth 


or l (simple) 


Value 


, l , or 2 


Default 


1 (high minus sign) 


Result Domain 




Type 


Integer 


Rank 





Shape 


i (scalar) 


Depth 


o (simple scalar) 


Description 





D NG controls the output representation of the APL negative sign, the high 
minus (~ ). Q NG affects the primitive functions monadic and dyadic format and 
the system functions OFI, Q VI, and D FMT. The following table describes the 
display of the minus sign for each of the possible values for UNG. 

Value Meaning in APL Output 

The minus sign (-) is used as the negative sign. 

1 The high minus sign (.NG in TTY mode) is used as the negative 
sign. 

2 The ASCII minus sign (- ) is used as the negative sign. 
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When DNG = 2, negative numbers are preceded by an APL "+" symbol when 
formatted by ¥ and D FMT. Because APL "+" prints as an ASCII "-", you can use 
D NG = 2 to handle negative numbers in strings that will be read or written in 
ASCII. Note that Q FI and Q VI recognize negative numbers that are preceded 
by an APL "+" symbol as negative numbers. 

The value of DNG is saved when you save the active workspace, and DNG can 
be localized in user-defined operations. 

Possible Errors Generated 



9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (NOT SINGLETON) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

15 DOMAIN ERROR (PARAMETER OUT OF RANGE) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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D NL Constructing a List of Names 
Type 

Ambivalent System Function 

Form 

name-list *- UNL name-classes 
name-list *■ letter-list QNL name-classes 

Left Argument Domain 



T^e 


Character 


Shape 


Vector domain 


Depth 


or l (simple) 


Right Argument 


Domain 


Type 


Near-integer 


Shape 


Vector domain 


Depth 


o or l (simple) 


Result Domain 




Type 


Character 


Rank 


2 


Shape 


Matrix 


Depth 


1 (simple) 



Description 

ONL lists the names of all existing APL objects belonging to the name classes 
specified in the argument. APL objects include user-defined objects, system 
variables, and system functions. 
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The right argument specifies one or more name classes. The possible values for 
the right argument and the classes those values represent are as follows: 



Value Names Returned 



5 Niladic system functions 

~ M- Groups 

~ 3 Monadic, dyadic, and ambivalent system functions 

~ 2 System variables 

1 Labels 

2 User-defined variables 

3 User-defined functions 

4 User-defined operators 



Note that Q NL returns the current local name of an object rather than the 
global name. For example: 

VF;F rF IS A FUNCTION (3) AND A VARIABLE (2) 

[1] F+-1 o WREAK 'STOP F' V 

ONE 3 aTHIS QUERY RETURNS THAT F IS A FUNCTION 
F 

F ^EXECUTE F, WHICH GETS SUSPENDED 
STOP F 

UNL 2 nfftW THE MOST LOCAL F IS A VARIABLE 
F 

UNL 3 nTHE FUNCTION F IS NO LONGER LISTED 

(APL outputs a blank line.) 

The result of QNL is a character matrix. If the right argument is empty, or if 
there are no objects belonging to the specified name class, the result is p 
' ' . Otherwise, each row contains the name of one object. All rows have the 
same number of columns; D NL pads the ends of the shorter names with blanks. 

APL returns the objects of each name class in QAV order. When the right 
argument specifies more than one name class, APL catenates the alphabetical 
lists without merging them together. The order of the lists is as follows: 

• Niladic system functions 

• Monadic, dyadic, and ambivalent system functions 

• System variables 

• User-defined names 
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The dyadic form of Q NL allows you to restrict the name list to names beginning 
with the characters in the left argument. For example, the following constructs 
a name list of function names whose initial letters are A through F : 

NLIST+- 'ABCDEF' QNL 3 

The left argument of QNL, if used, must be a character array whose shape 
is in the vector domain. The order of the characters does not affect the Q A V 
order of the result. APL ignores the left argument if it is empty. Note that 
the first character of a system function or system variable is the Q symbol; if 
you use the dyadic form of □ NL and specify either ~ 5 , ~ 3 , or ~ 2 in the right 
argument, APL ignores the D as it searches for the names beginning with the 
letters contained in the left argument. 

The following example shows the construction of a matrix containing the 
names of variables in the active workspace that begin with the letter V: 

NLIST+'V DM 2 

NLIST 
VAR1 
VAR2 
VAR203 
VBMAX 

The D NL system function is useful for a variety of purposes. For example: 

• D NL can interact with Q CR to create functions that automatically display 
the definitions of some or all the functions in the workspace. 

• With QEX, QNL can dynamically erase all the named objects in a certain 
category. You can also use D NL to design a function that will clear a 
workspace of all but a preselected collection of named objects. 

• In its dyadic form, D NL can guide you in choosing names while you develop 
or interact with a workspace. 

Possible Errors Generated 



9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT A LETTER) 

15 DOMAIN ERROR (NOT AN INTEGER) 
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15 DOMAIN ERROR (PARAMETER OUT OF RANGE) 
2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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UNUM Digits 
Type 

Niladic System Function 

Form 

1 0123456789 ' +- QNUM 

Result Domain 

Type Character 

Rank l 

Shape 1 o 

Depth l (simple) 

Description 

UNUM is a subset of DAV. ONUM returns a vector of the 10 digits 0123456789, 
or, expressed in terms of D A V: 

D47[48+il0] 
For example: 

UNUM 
01231+56789 

0I(H0 

OAVxUNUM 
48 49 50 51 52 53 54 55 56 57 

Possible Errors Generated 

None. 



APL Reference Manual 2-135 



System Variables and Functions 

D OM Indexing a Boolean Vector 



□ OM Indexing a Boolean Vector 
Type 

Monadic System Function 

Form 

indexes +- Q OM near-Boolean 

Right Argument Domain 



^pe 


Near-Boolean 


Shape 


Vector domain 


Depth 


or l (simple) 


Result Domain 




Type 


Integer 


Rank 


i 


Shape 


+ / near-Boolean 


Depth 


l (simple) 



Implicit Arguments 



D 10 (D OM B when Q 10 +- l is identical 
to 1 + DOM B when QIO *■ 



Description 



DOM produces indexes showing the locations of the Is in a Boolean vector. If 
the argument is empty, the result is i o . For example: 

MERZ HO 10 11 10 010 

DOM MERZ 
it 6 7 8 11 

A *- <THE QUICK BROWN FOX' 

QOM A = ' ' 
t 10 16 

Note that the following definition applies: DOM A «-->- A 1 1 p ,A 
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Possible Errors Generated 

9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 
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□ PA CK Packing and Unpacking Data 
Type 

success I fail *■ data-packets UPACK variable-names 

Monadic Argument Domain 

Type Character 

Shape Matrix domain 

Depth or 1 (simple) 

Monadic Result Domain 

Type Integer 

Rank l 

Shape Vector 

Depth l (simple) 

Dyadic Left Argument Domain 

Type Near-integer 

Shape Vector 

Depth l (simple) 

Dyadic Right Argument Domain 

Type Character 

Shape Matrix domain 

Depth or 1 (simple) 

Dyadic Result Domain 

Type Boolean 

Rank l 

Shape Vector 

Depth l (simple) 
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Description 

D PA CK allows you to pack and unpack data of different types into a single 
variable known as a packet. The monadic form packs data, and the dyadic 
form unpacks it. 

UPACK differs from D COQ and Q CIQ because it allows you to pack and unpack 
variables of different data types with only one invocation of the □ PACK 
function. (Otherwise, to pack variables you invoke Q COQ once for each data 
type, and then catenate the results into a single variable; to unpack a variable 
you undo the catenation and then invoke □ CIQ once for each data type.) 
Unlike UCOQ, UPACK does not convert data into different data types before 
packing it. 

Use monadic UPACK to pack data. When you specify a single variable, Q PACK 
creates a □ COQ packet with a header; it does not perform any data type 
conversion before creating the packet. When you specify more than one 
variable, UPACK creates individual UCOQ packets for each variable and 
combines them in a single logical record. 

The argument to the monadic form contains the names of the user-defined 
variables you want to pack. If the argument to monadic □ PACK is empty, then 
the result is i . 

Use dyadic UPACK to unpack data. The left argument must be a vector; it 
identifies a packet that was created by monadic D PACK. 

The right argument contains the names you want to assign to the individual 
packets as they are unpacked from the left argument. It must have one row 
for each individual packet in the left argument. Each name can have a name 
class of or 2 (undefined name or user-defined variable). When the name class 
is 0, the variable becomes defined. When the name class is 2, APL redefines 
the variable. If the right argument contains a blank row, APL does not unpack 
the individual packet associated with that row. 

The result indicates whether the names contained in the right argument 
have been successfully assigned the Q CIQ value of the individual packets. A 
indicates an unsuccessful assignment (caused by a blank row in the right 
argument), and a 1 indicates a successful assignment. Each position in the 
result corresponds to a row in the right argument. If the left or right argument 
is empty, then the result is i . The header generated by □ PACK has the 
following format: 
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length = 4 + n 



type =1 



rank = 1 



n 



start of D coq packets 



end of D coq packets 



NU-2235A-RA 



Each large box represents a longword. length is the length of the result (an 
integer vector) of monadic UPACK. type always has a value of 1, indicating 
32-bit integers, rank is always 1. n indicates the length of the data section of 
the packet. The data section (elements 5 through 5 + n) contains the integer 
representations of the individual packets. 

The following example shows how the individual packets created by UPACK 
relate to the packets created by D CIQ. Note the use of Q BOX in the right 
argument to dyadic UPACK; it is used to facilitate the entry of the names of the 
individual packets as a character matrix: 

fl+2 4 p 'ABCD' 

D <- AA *■ A UCOQ 2 
91151231+5 

D +■ BB *■ B UCOQ 2 
5 2 2 H 168423481+9 1681234849 

D+QPACK UBOX 'A 
B< 

D 
20 11 16 91151234575224 1684234849 1684234849 

D *■ N «- (pAA) + pBB 
16 

D = ((ff+4), 1 1, N), AA,BB 
1 

D UPACK UBOX 'AAA 
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BBB< 

1 1 

AAA 
12 3 4 5 

AAA = A 
1 

BBB 
ABCD 
ABCD 



Possible Errors Generated 

9 RANK ERROR (MUST BE VECTOR) 

9 RANK ERROR (NOT MATRIX DOMAIN) 

10 LENGTH ERROR (ITEM COUNT MISMATCH) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (ILLEGAL NAME CLASS) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (INVALID CIQ HEADER) 

15 DOMAIN ERROR (INVALID LENGTH IN PACK HEADER) 

15 DOMAIN ERROR (INVALID RANK IN PACK HEADER) 

15 DOMAIN ERROR (INVALID RHO VECTOR IN PACK HEADER) 

15 DOMAIN ERROR (INVALID TYPE IN PACK HEADER) 

15 DOMAIN ERROR (NOT AN INTEGER) 

2 7 LIMIT ERROR (INTEGER TOO BIG) 
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D PP Print Precision 
Type 



System Variable 



Form 



DPP *■ digits-* 


of-precision 


integer-scalar 


<- UPP 


Value Domain 




Type 


Near-integer 


Shape 


Singleton 


Depth 


or l (simple) 


Value 


1 to 16 


Default 


10 



Result Domain 



TVpe 


Integer 


Rank 





Shape 


i 


Depth 


o (simple scalar) 


Description 





D PP determines how many significant digits are displayed in APL floating- 
point output. It does not affect the display of integers or the precision of 
internal calculations. It does affect the conversion of numbers to characters by 
the dyadic format function or the display of floating-point constants in Q CR and 

QVR. 

Legal values for Q PP are the integers 1 through 16. The default is 10. APL 
rounds off numbers that contain more digits than the setting. For example: 
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DPP 
10 

123156789.123456789 
123456789.1 

QPP+-5 

123456789.123456789 
1.234658 

DPP-i-15 

123456789.123456789 
123456789.123457 

QPP<-10 

^LEADING ZEROS ARE NOT SIGNIFICANT 
fiNOTE THAT ROUNDING MAY MAKE RESULT 
fiHAVE FEWER THAN QPP DIGITS 

Q+A+2 lpl 4 r 101 
0.009900990099 
0.0396039604 

DPP-f-11 

A 
0.009900990099 
0.039603960396 

DPP<-12 

A 
0.00990099009901 
0.039603960396 

The value of Q PP is saved when you save the active workspace and can be 
localized in user-defined operations. 

Possible Errors Generated 

9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (NOT SINGLETON) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

15 DOMAIN ERROR (PARAMETER OUT OF RANGE) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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UPW Print Width 
Type 

System Variable 

Form 

D PW *- print-positions 
integer-scalar +- D PW 



Value Domain 




TVpe 


Near-integer 


Shape 


Singleton 


Depth 


or l (simple) 


Value 


35 to 201+8 


Default 


Determined when APL is invoked 



Result Domain 



Type 


Integer 


Rank 





Shape 


i 


Depth 


(simple scalar) 


Description 





D PW specifies the maximum number of characters that can appear on a 
terminal output line before a <CRxLF> is performed. Q PW has no effect on 
the length of input lines. The default uses the current VMS setting for set 
terminal/width=n . 

If an output line requires more than PW character positions, printing 
continues on succeeding indented lines. For example: 

QPW+3S 

A+'THIS IS A TEST OF THE PRINT WIDTH VARIABLE' 

A 

THIS IS A TEST OF THE PRINT WIDTH V 
ARIABLE 
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However, if a line in an error message is longer than D PW characters, it is 
truncated; it is not continued on the next line. If truncating the line prevents 
APL from displaying the particular point in the line at which the error was 
discovered, APL cuts off enough characters from the beginning of the line to 
allow the part in error to be displayed. 

The value of Q PW is saved when you save the active workspace and can be 
localized in user-defined operations. When you exit from APL, the original 
terminal-width value is restored. 

Actually, APL never changes your terminal width; in effect, it overrides the 
width by preventing lines from wrapping and then by formatting any output 
based on the value of □ PW. 

Note that if you interrupt your APL session (for example, by executing a ) PUSH 
command) and then execute an operating system command to change the value 
of the terminal width, the value of D PW is not changed when you return to 
APL. For example: 

) CLEAR 
CLEAR US 

LW fiQPW INITIAL VALUE = SYSTEM TERM NIDTR 

80 

QPtf<-6 5 nCHANGE LW TO 6 5 

^INTERRUPT APL SESSION 

)PUSH 
$SET TERMINAL/WIDTH = 72 
$ LOGOUT 
Process USER logged out at 16-NOV-1990 13:24:43.11 

DPW nLW NOT CHANGED TO 7 2 

65 

If you exit APL via a panic exit, your system terminal width takes effect, but 
your terminal retains the APL setting that prevents lines from wrapping, 
regardless of the way wrapping was handled before you began your APL 
session. If you want lines to wrap, execute the DCL command set terminal 

/wrap. 

Possible Errors Generated 

9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (NOT SINGLETON) 

1 5 DOM A IN ERROR ( ENCLOSED ARRA Y NO T ALLOWED ) 
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15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

15 DOMAIN ERROR (PARAMETER OUT OF RANGE) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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D Q CO Copying Objects from a Workspace 
Type 

Monadic System Function (quiet) 

Form 

message +■ UQCO wsname ^object-names^ 

Argument Domain 



Type 


Character 


Shape 


Vector domain 


Depth 


or l (simple) 


Result Domain 




Type 


Character 


Rank 


l 


Shape 


Vector 


Depth 


l (simple) 


Qualifiers 





/password [:pivl 

If a workspace is saved with a password, you must specify the password to 

copy objects from the workspace. 

/CHECK 

The optional / CHECK qualifier causes APL to examine the workspace for 
possible corruption (damage to the internal structure of the workspace). If 
damage is detected, a message is displayed and APL tries to recover as much 
information as possible from the workspace and continues the copy. The 
recovered workspace may be missing APL variables, user-defined operations, 
and other APL objects that were damaged. The user must determine what 
named objects have been removed from the workspace. 
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Description 

DQCO (quiet copy) retrieves global objects from a workspace and places them 
into your active workspace. 

The argument has four parts: the name of the workspace from which you want 
to copy the objects, an optional password, an optional qualifier (/CHECK), and 
an optional list of objects to be copied. 

Use the list of objects to identify the specific objects you want to copy. If you 
omit the list, all global user-defined operations, global variables, and groups 
are copied. When you specify the objects, you can use the * and -f wildcards. 
Note that DQCO does not transfer local values for variables, functions, and 
operators, nor does it copy the state indicator or system variables like the print 
width, index origin, or significant digits settings. 

The □ QCO system function performs the same operation as the ) COPY system 
command (see Chapter 3). DQCO returns as its result a character vector 
containing the usual ) COPY command message. However, because DQCO is a 
quiet function, if it is the leftmost function in the statement, its result is not 
displayed on the terminal unless there is an error (warnings are not displayed). 
For example: 

)C0PI AB CALC 
SAVED TUESDAY 6-TOK-1990 17: 4-9: 10. 1M- 16 BLKS 

) CLEAR 
CLEAR WS 

QQCO <AB CALC 

) CLEAR 
CLEAR US 

MSG^QQCO 'AB CALC TOT' 

MSG 
SAVED TUESSDAY 6-TO7-1990 17:49:10.14 13 BLKS 
NOT FOUND: TOT 

If your active workspace contains objects with the same names as those in 
the copied workspace, DQCO replaces the global (but not the local) values in 
your active workspace with the copied ones. For example, if B is a variable in 
the active workspace with a global value of 10 and a local value of 5, and the 
workspace being copied has a variable B with a global value of 20, the active 
workspace after DQCO executes will have a variable B with a global value of 20 
and a local value of 5. A pendent or suspended operation is not replaced, and 
an operation being created in the workspace being copied is not copied. 
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When you copy a group, all members of the group are copied along with their 
values. However, if a member of a group is itself a group, APL copies only the 
group name and not its values. For example, suppose the group GROUP i has 
as members the variables A and B , and the group GR0UP2. Also suppose that 
GR0UP2 has as members the variables C and D. Then, if you copy GROUPl, you 
copy the values of A and B , but only the name of GR0UP2 , not the values of C 
and D. 

If the object list contains objects that are not in the specified workspace, APL 
returns the warning message NOT FOUND followed by the names (separated 
by tabs) that were not found. The objects that were found are still copied, 
however. 

Examples: 

) CLEAR 
CLEAR US 

)C0PJ TAB 
SAVED TUESDAY 6-TOF-1990 17:51:20.88 13 BLKS 

A 
1 

B 
2 

C 
11 VALUE ERROR 

C 

) CLEAR 
CLEAR US 

MSG+UQCO T 

MSG 
SAVED TUESDAY 6-^01^-1990 17:51:20.88 13 BLKS 

A 
1 

S 
2 

C 
3 

) CLEAR 
CLEAR WS 

MSG+0QCO 'TAB' 

A 
1 

B 
2 

C 
11 VALUE ERROR 

C 

A 
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) CLEAR 
CLEAR WS 

)C0PY TAD 
SAVED TUESDAY 6-^07-1990 17:51:20.88 13 BLKS 
MOT FOUND: D 

A 
1 

B 
11 VALUE ERROR 



) CLEAR 
CLEAR HS 

MSG+UQCO 'TAD' 

MSG 
SAVED TUESDAY 6-ff07-1990 17:51:20.88 13 BLKS 
NOT FOUND: D 

pMSG 
59 

Possible Errors Generated 

9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (ILLEGAL EMPTY ARGUMENT) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (FILE SPECIFICATION IS MISSING) 

15 DOMAIN ERROR (INCORRECT TYPE) 
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D QLD Loading a Workspace 
Type 

Monadic System Function (quiet) 

Form 

QQLD wsname 

Argument Domain 



Type 


Character 


Shape 


Vector domain 


Depth 


or l (simple) 


Result Domain 




None. 




Qualifiers 





/PASSWORD l.pwl 

Specifies the password used when the workspace was saved. If a workspace is 

saved with a password, you must specify the password to copy objects from the 

workspace. 

/CHECK 

The optional /CHECK qualifier causes APL to examine the workspace for 
possible corruption (damage to the internal structure of the workspace). If 
damage is detected, a message is displayed and APL tries to recover as much 
information as possible from the workspace and continues the copy. The 
recovered workspace may be missing APL variables, user-defined operations, 
and other APL objects that were damaged. The user must determine what 
named objects have been removed from the workspace. You must use the 
) SA VE command if you want to maintain an undamaged version of the 
recovered workspace. 
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Description 

QQLD (quiet load) makes the specified workspace the active workspace by 
replacing the currently active workspace and destroying its contents. 

The argument has three parts: the name of the workspace to be loaded, 
an optional password, and an optional qualifier (/CHECK). For example, the 
following loads a workspace named ABC, which was saved with the password 

JOHN: 

UQLD <ABC/PASSUORD:JOHN' 

Note that the QQLD system function performs the same operation as the )LOAD 
system command (see Chapter 3), but Q QLD does not print messages on the 
terminal unless there is an error. 

QQLD does not return a result in the usual sense or display a message when it 
is successful, because the context in which Q QLD was executed is replaced by 
the loaded workspace. 

If the DLX system variable has a value in a workspace, it executes when QQLD 
is used to load the workspace, except if the top of the state indicator stack 
contains an execute function (see the Execute function described in Chapter 1 
for details), or if the workspace was saved in function-definition mode (if it was, 
you remain in function-definition mode after the workspace is loaded). If the 
workspace was saved inside input, the QLX expression is executed only after 
the pendent D input is removed from the state indicator stack. For example: 

A 
1 

) CLEAR 
CLEAR US 

UQLD 'I" 

} MSID 
T 

A 
1 

Possible Errors Generated 



9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (ILLEGAL EMPTY ARGUMENT) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 
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15 DOMAIN ERROR (FILE SPECIFICATION IS MISSING) 
15 DOMAIN ERROR (INCORRECT TYPE) 
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□ QPC Copying Objects with Protection 
Type 

Monadic System Function (quiet) 

Form 

message -*- D QPC wsname \object-names\ 

Argument Domain 



Type 


Character 


Shape 


Vector domain 


Depth 


o or i (simple) 


Result Domain 




Type 


Character 


Rank 


l 


Shape 


Vector 


Depth 


1 (simple) 


Qualifiers 





/PASSWORD [:pw] 

Specifies the password used when the workspace was saved. If a workspace is 

saved with a password, you must specify the password to copy objects from the 

workspace. 

/ CHECK 

The optional / CHECK qualifier causes APL to examine the workspace for 
possible corruption (damage to the internal structure of the workspace). If 
damage is detected, a message is displayed and APL tries to recover as much 
information as possible from the workspace and continues the copy. The 
recovered workspace may be missing APL variables, user-defined operations, 
and other APL objects that were damaged. The user must determine what 
named objects have been removed from the workspace. You must use the 
) SA VE command if you want to maintain an undamaged version of the 
recovered workspace. 
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Description 



QQPC (quiet copy with protection) is the same as the DQCO system function 
except that Q QPC does not replace objects in the active workspace with objects 
of the same name in the copy workspace. Instead, APL returns the warning 
message NOT COPIED followed by the names of objects (separated by tabs) that 
were not copied. 

As with DQCO, the argument for DQPC represents the name of the workspace 
from which you want to copy the objects, followed by three optional items: a 
password, a qualifier (/CHECK), and a list of objects. When you specify the 
objects, you can use the * and -r wildcards. 

When copying groups, Q QPC does not copy any members of the group that have 
the same name as a name already in the active workspace. If the group name 
itself is the same as a group name in the active workspace, APL does not copy 
the group name or any members of the group. 

If the list to be copied contains an object that is not in the specified workspace, 
APL returns the warning message NOT FOUND, followed by the names of the 
objects (separated by tabs) that were not found. The objects that were found 
are still copied, however. 

The D QPC system function performs the same operation as the )PCOPY system 
command (see Chapter 3). D QPC returns as its result a character vector that 
contains the usual )PCOPY command message. However, because DC CO is a 
quiet function, if it is the leftmost function in the statement, the result is not 
displayed on the terminal unless there is an error (warning messages are not 
displayed). 

Examples: 

) CLEAR 
CLEAR US 

A+20 

)PC0PY T 
SAVED TUESDAY 6-/P0F-1990 17:51:20.88 13 BLKS 
NOT COPIED: A 

A 
20 

B 
2 

C 
3 
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) CLEAR 
CLEAR US 

A+20 

MSG+-DQPC >T' 

MSG 
SAVED TUESDAY 6-ffO7-1990 17:51:20.88 13 BLKS 
NOT COPIED: A 

A 
20 

B 
2 

C 
3 

MSG+-QQPC 'TAD' 

MSG 
SAVED TUESDAY (,-NOV-lSSO 17:51:20.88 13 BLKS 
NOT FOUND: D 
NOT COPIED: A 

pMSG 
74 

Possible Errors Generated 

9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (ILLEGAL EMPTY ARGUMENT) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 
15 DOMAIN ERROR (FILE SPECIFICATION IS MISSING) 
15 DOMAIN ERROR (INCORRECT TYPE) 
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D R Monitoring Variable Changes 
Type 

System Variable 

Form 

OR ■*- any 
old-value «- OR 

Value Domain 

Type Any 

Shape Any 

Depth Any 
Default 

Result Domain 



Type 


Any 


Rank 


Any 


Shape 


Any 


Depth 


Any 



Description 



D R and Q L are system variables that are implicitly used by D WA TCH. WA TCH is 
a system function that is used to monitor any changes in one or more variables. 
When a change occurs in a monitored variable, APL assigns information to OR 
and □ L : R contains the previous value of the changed variable; □ L contains 
a character vector showing the name of the variable that has changed. APL 
assigns this information regardless of whether monitoring is set for signal or 
display mode. 

Immediately after a WATCH event occurs, OR and OL contain the new 
information resulting from the event. However, this information may change 
as an operation continues execution (this is especially true if an error occurs 
during an assignment or reference of a variable that is associated with a 
watchpoint). 
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Both □ R and Q L can be localized, explicitly assigned values of any type, and 
saved in the workspace. 

Note that you cannot include Q R or Q L in the right argument to dyadic 

D WATCH. 

Possible Errors Generated 

None. 
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D RELEASE Unlocking Shared Records 
Type 

Monadic System Function (quiet) 

Form 

i <- D RELEASE charts 

Argument Domain 

Type Near-integer 

Shape Vector domain 

Depth o or l (simple) 

Value "999 through 999 (but not ) 

Result Domain 



Type 


Numeric 


Rank 


l 


Shape 


(empty) 


Depth 


l (simple) 



Description 

D RELEASE unlocks any locked records in files associated with the channel 
numbers specified in the argument. The absolute values of chans represent the 
channels associated with the files you want to unlock. 

U RE LEASE is quiet; it does not return a result if it is the leftmost function 
in a statement. When it is not the leftmost function, DRELEASE returns an 
empty numeric vector. If its argument is empty, DRELEASE has no effect and 
its result is an empty vector. Note that APL performs a URELEASE on all open 
files whenever a ) MON command is executed. 

If you read a record that you do not intend to rewrite, it is a good idea to 
unlock it as soon as possible, because other users who try to retrieve it are put 
in a wait state until the record becomes available. 

D RELEASE is described the VAX APL User's Guide along with other file I/O 
information. 
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Possible Errors Generated 

9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (NOT AN INTEGER) 

15 DOMAIN ERROR (INVALID CHANNEL NUMBER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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UREP Replication 
Type 

Dyadic System Function 

Form 

A DREP B A QREPLK1 B 

Left Argument Domain 



TVpe 




Near-integer 


Shape 




domain 


Depth 




or l (simple) 


Right Argument 


Domain 


TVpe 




Any 


Shape 




Any 


Depth 




Any 


Result Domain 






Type 




as right argument 


Rank 




itpps 


Shape 




( (if-l)ApS) , (+/ \A),K\ p B (for D 10 l) 


Depth 




ir = s 


Implicit Arguments 




None. 







Description 

UREP builds arrays by specifying the items to be deleted, preserved, or 
duplicated from an existing array, and by indicating where fill items are to be 
added in the new array. When items are preserved or deleted, this is known 
as compression (the left argument is Boolean). When items are duplicated, 
deleted, or filled, this is known as replication (the left argument is integer). 
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DREP works the same as the compress and replicate derived functions. The 
difference between DREP and the slash operator is that you can use DREP as 
an operand to an operator. Operators cannot be used as operands to operators. 
DREP applies along the last axis of B unless modified by an explicit axis (K) in 
brackets. The shape of the result is the same as the original array B except 
along the applicable axis ( p B ) [Jf] . The shape of that axis becomes the sum of 
the absolute value of the items in A ( + / | A ) . 

The following examples show DREP with the each (" ) operator. Although 
the variables A and C are nested in the examples, they conform to the left 
argument domain requirement that specifies a simple array. This is because 
the each operator reduces the nesting by one level: 

D-M-t-U 1) (1 "1 2) 

+ + + + 

|1 1| |1 "1 2| 

+ + + + 

I>B^(2 3pi6) (H 3p' AECDEFGHIJKL') 

+ 1 + + 

|1 2 3| |4BC| 
I 4 5 6 | \DEF\ 

+ + \GHI\ 

\JKL\ 

+ + 

^ATTEMPT TO USE OPERATOR AS ARG TO 
A/"B rtAPL EVALUATES AS (A/)"B 

15 DOMAIN ERROR (ENCLOSED/ HETEROGENEOUS ARRAY NOT ALLOWED) 
A/"B aAPL EVALUATES AS [AI)"B 

A 

A UREP"B (tREPLICATE ITEMS OF B USING THE ITEMS OF A 

+ + + + 

|1 3| \A CC\ 
|t 6| \D FF\ 
+---+ |ff II| 

| J III 

+ + 

A QREP121" B s SECOND AXIS^ DEFAULT IN THIS CASE 

+ + + + 

|1 3| \A CC\ 
\k 6| \D FF\ 
+ - — + Iff III 

\J LL | 

+ + 

D-K>(2 '1 0) (1 1 1) 
+ --____ + + + 

|2 "1 0| |1 1 1| 
+ + + + 
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C UREPLll" B nUSE QREP WITH AXIS ARGUMENT 

+ + + + 

|1 2 3| \ABC\ 
| 1 2 3 i \DEF\ 
| 1 I «7X£ | 
+ + + + 

Possible Errors Generated 

9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 

2 8 AXIS RANK ERROR (NOT VECTOR DOMAIN) 

2 9 AXIS LENGTH ERROR (NOT SINGLETON) 

3 AXIS DOMAIN ERROR ( SEMICOLON LIST NOT ALLOWED ) 
30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 
3 AXIS DOMAIN ERROR (INCORRECT TYPE) 

3 AXIS DOMAIN ERROR (NOT AN INTEGER) 

3 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 

3 AXIS DOMAIN ERROR (RIGHT ARGUMENT HAS WRONG RANK) 
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D RESET Resetting the State Indicator 
Type 

Niladic System Function 

Form 

n RESET 

Result Domain 

None. 

Description 

RESET clears the state indicator. When the state indicator is clear, no user- 
defined operations are suspended, no quad input requests or execute functions 
are pending, and the ) SI system command (see Chapter 3) does not return a 
value. 

D RESET does not return a value. 

Possible Errors Generated 

None. 
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D REWIND Returning Next-Record Pointer to Start of File 
Type 

Ambivalent System Function (quiet) 

Form 

iO^D REWIND chans 

i +- key -of -reference Q REWIND chans 

Monadic Argument Domain 

Type Near-integer 

Shape Vector domain 

Depth or l (simple) 

Value ~ 9 9 9 through 9 9 9 (but not ) 

Dyadic Left Argument Domain 

Type Near-integer 

Shape Singleton 

Depth o or l (simple) 

Value o through 255 inclusive 

Dyadic Right Argument Domain 

Type Near-integer 

Shape Singleton 

Depth or l (simple) 

Value "999 through 999 (but not o ) 
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Result Domain 



type 


Numeric 


Rank 


l 


Shape 


(empty) 


Depth 


l (simple) 


Description 





□ REWIND allows you to reposition the next record pointer to the first record 
of a file without closing the file. The absolute values of charts represent the 
channels associated with the files you want to rewind. 

With the monadic form, you can specify a vector of channel numbers in the 
right argument. This will rewind each of the files associated with the specified 
channel numbers. If any of the files have a keyed organization, APL performs 
the rewind on the primary key of reference. 

Use the dyadic form for keyed files when you want APL to perform the rewind 
on a key of reference other than the primary key. The right argument specifies 
the channel number associated with the keyed file. The left argument specifies 
the key of reference. Zero (0) indicates the primary key, one (1) indicates the 
secondary key, and so on. You can specify only one file at a time when you 
invoke dyadic Q REWIND. 

Q REWIND is described in the VAX APL User's Guide along with other file I/O 
information. 

Possible Errors Generated 

Monadic Form 

9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INTEGER TOO LARGE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

15 DOMAIN ERROR (INVALID CHANNEL) 

15 DOMAIN ERROR ( CHANNEL NOT ASSIGNED) 
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15 DOMAIN ERROR (FILE IS ASSIGNED WRITE ONLY) 

3 3 10 ERROR {INVALID KEY OF REFERENCE FOR $GET/$FIND) 
Dyadic Form 

9 RANK ERROR {NOT A SINGLETON) 

15 DOMAIN ERROR ( CHANNEL NOT ASSIGNED) 

15 DOMAIN ERROR (CHANNEL NOT ASSIGNED TO A KEYED FILE) 

15 DOMAIN ERROR (ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (INVALID CHANNEL) 

15 DOMAIN ERROR (NOT AN INTEGER) 

15 DOMAIN ERROR (PARAMETER OUT OF RANGE) 

2 7 LIMIT ERROR ( INTEGER TOO LARGE) 

3 3 10 ERROR (INVALID KEY OF REFERENCE FOR $GET/$FIND) 
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D RL Link 
Type 



System Variable 



Form 



QRL *■ random-seed 


integer-scalar *- 


QRL 


Value Domain 




iy pe 


Near-integer 


Shape 


Singleton 


Depth 


or l (simple) 


Value 


~ 2* 30 through ~~ 1+2* 30 


Default 


695197565 



Result Domain 



T>pe 


Integer 


Rank 





Shape 


i (scalar) 


Depth 


o (simple scalar) 


Description 





Q RL sets the seed of the pseudo-random-number generator used with the roll 
and deal functions (see Chapter 1). □ RL can be set by the user, and is also set 
implicitly by the system when roll and deal are executed. 

Every time you execute a roll or deal function, the value of the random link 
changes. The value of Q RL is saved with a workspace and can be localized in 
user-defined operations. For example: 
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URL Link 



QRL 
695197565 

5?5 
4 2 3 15 

URL 
"H7060346 

5?5 
4 12 3 5 

URL 
1636171117 

Possible Errors Generated 

9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (NOT SINGLETON) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 



APL Reference Manual 2-169 



System Variables and Functions 

USF Quad Input Prompt 



D SF Quad Input Prompt 
Type 



System Variable 


i 


Form 




D SF «- prompt 
char-vector *■ Q SF 


Value Domain 




Type 

Shape 

Depth 

Value 

Default 


Character 
Vector domain 
or l (simple) 

prompt lengths 255 keystrokes 
' D : <CRxLF> 6-spaces ' 


Result Domain 




Type 
Rank 
Shape 
Depth 


Character 
l 

Vector 
l (simple) 


__ 





D SF specifies the text to be used as the prompt for quad input (see the 
VAX APL User's Guide). You can use any printing characters in the prompt. 

The prompt is printed each time a request is made for quad input (0 ). For 
example: 
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13 

□ : 



,4<-3+D+5 

5 

A 

'INPUT' 



INPUT 

USF<-'WHAT IS YOUR NAME? ' 

OQ 
WHAT IS YOUR NAME? ' CARL A' 

C 

CARLA 

Note that you must enclose character-type quad input in single quotation 
marks. 

The maximum length for Q SF is 255 keystrokes (a keystroke occurs any time 
you press a key on the keyboard, including the Space bar and the Backspace 
key). The value of □ SF is saved when you save the active workspace and can 
be localized in user-defined operations. 

Possible Errors Generated 

9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

2 7 LIMIT ERROR (ARGUMENT STRING IS TOO LONG) 
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D SIGNAL Signaling Errors 
Type 

Ambivalent System Function 

Form 

error-number 

message-text Q SIGNAL error-number 

Monadic Argument Domain 

Type Near-integer 

Shape Singleton 

Depth or l (simple) 

Value Any APL error number (except 7 5, 115 to 49 9 or greater 

than 9 9 9) 

Dyadic Left Argument Domain 



Type 


Character 


Shape 


Vector domain 


Depth 


or l (simple) 


Dyadic Right Argument Domain 


Type 


Near-integer 


Shape 


Singleton 


Depth 


or 1 (simple) 


Value 


Any APL error number (except 75, 115 to 499 or greater 




than 9 9 9) 


Result Domain 




None. 
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Description 



D SIGNAL allows you to signal an error to the caller of the operation in error; 
thus, the way a user-defined operation that executes Q SIGNAL fails is similar 
to the way a primitive function fails. 

In both the monadic and dyadic forms, the right argument is the error number. 
You can use an existing APL error number (except 75) as listed in Appendix A, 
or you can define your own number (within the range 500 through 999). 

The left argument (dyadic form), if used, is the text of the error message for 
the error you are signaling. For example: 

'WILL NOT ACCEPT NEGATIVE NUMBERS' QSIGNAL 501 

This statement, if executed within a user-defined operation (Q SIGNAL generally 
appears within a user-defined operation, but this is not a requirement), signals 
the following error: 

501 WILL NOT ACCEPT NEGATIVE NUMBERS 

The message is followed by the rest of the APL standard three-line error 
message; that is, the text of the line in error and a caret pointing to the part of 
the line in error. The three-line error message generated by Q SIGNAL becomes 
the value of D ERROR. 

If the error number you supply to Q SIGNAL is the number of an APL error, the 
message displayed (and stored in □ ERROR) is the error message that coincides 
with that number (see Appendix A for a description of APL error messages), 
and the left argument to D SIGNAL becomes the secondary error message 
(displayed in parentheses following the primary error message). If you do not 
use an existing APL error number, and you leave the left argument blank, APL 
signals the following error: 

ERROR SIGNALED 

In the following example, notice that the error is signaled at the level of the 
caller, function H , not at function F : 
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ftFUNCTION F HAS QSIGML 
VF A 
[1] -*U>0)/3 

[2] 'WILL NOT ACCEPT NEGATIVE NUMBERS' QSIGNAL 15 
[3] 'FUNCTION CONTINUING NORMALLY' 
[4] V 

^FUNCTION H CALLS F 
IE A 
[1] F A 
[2] V 

H 5 
FUNCTION CONTINUING NORMALLY 
H 7 
15 DOMAIN ERROR (WILL NOT ACCEPT NEGATIVE NUMBERS) 
tf[l] F A 

A 

You can use error number 80 to signal a status condition to the DCL 
interpreter. The right argument to Q SIGNAL must be 80, and the left argument 
is a character string representing a hexadecimal number that is the status code 
you want to return to VMS. The status code returned is stored as the value of 
the global symbol $STATUS. For example: 

'12UBC1' QSIGNAL 80 

(APL returns control to DCL) 
$show symbol $status 
$STATUS == "%X0123ABC1" 

The low-order three bits of $STATUS represent the severity level of the error 
signaled and are contained by the global symbol $SEVERITY. For example: 

$ show symbol $severity 
$SEVERITY == "1" 

DCL command procedures interpret the $SEVERITY value 1 to mean success, 
and the value 2 to mean error. (For details on command procedures, see the 
Guide to Using VMS Command Procedures.) In the following command 
procedure, the first line means branch to the label ERROR any time 
$SEVERITY becomes equal to 2: 

on error then goto error 
$ apl 



(APL statements) 



$ write sys$output"No Error From APL" 
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$ exit 

$ error: 

$ write sys$output"APL Returned Error" 

If ' 2 ' D SIGNAL 8 is executed during the APL session, the command 
procedure branches to ERROR and displays the message "APL Returned 
Error". If ' l ' Q SIGNAL 8 is executed, the command procedure displays "No 
Error From APL" and then exits. 

For more information on the use of Q SIGNAL, see Chapter 3 in the VAX APL 
User's Guide. 

Possible Errors Generated 



15 DOMAIN ERROR {CANNOT SIGNAL EOF) 

15 DOMAIN ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (NOT SINGLETON) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 

15 DOMAIN ERROR (PARAMETER OUT OF RANGE) 
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D SINK Discard Output 


Type 




System Variable 


Form 




D SINK +■ any- 


value 


i +■ D SINK 




Value Domain 




Type 


Any 


Shape 


Any 


Depth 


Any 


Result Domain 




Type 


Numeric 


Rank 


l 


Shape 


(empty) 


Depth 


1 (simple) 


Description 





USINK immediately discards any value that you assign to it. The value of 
D SINK is always i . 

□ SINK is useful inside a user-defined operation; it allows you to discard output 
that you do not want stored or displayed. 

D SINK can be localized and is saved with the workspace; however, neither 
operation has any effect. 

Possible Errors Generated 

None. 
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D SS String Search 
Type 

Dyadic System Function 

Form 

Boolean +■ pattern-string Q SS target-string 

Left Argument Domain 



Type 


Character 


Shape 


Vector domain 


Depth 


or l (simple) 


Right Argument 


Domain 


Type 


Character 


Shape 


Vector domain 


Depth 


or l (simple) 


Result Domain 




Type 


Boolean 


Rank 


l 


Shape 


p , target-string 


Depth 


l (simple) 


Description 





D SS searches the right argument for every appearance of the character string 
specified in the left argument. This allows you to determine where a substring 
begins in the searched string. 

The result is a Boolean vector equal to the length of the ravel of the right 
argument. The function places a 1 in any position corresponding to the start of 
the specified string. For example: 
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APR 


MAY 


JUS 










JUL 


AUG 


SEP 










OCT 


NOV 

4 


DEC 

11 f 


)( 


'AUG 




OSS 


















































1 















*issi< ass 'Mississippi' 

01001000000 

Q+MONTHS+H Up' JAN FEB MARAPR MAY JUNJUL AUG SEPOCT NOV DEC 

JAN FEB MAR 



.MONTHS) 



00000000000 

Possible Errors Generated 

9 RANK ERROR {NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 
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□ STOP Suspending Operation Execution 
Type 

Ambivalent System Function (monadic form is query) 

Form 

line-numbers +- Q SI 'OP function-names 

success I fail +■ line-numbers □ STOP function-name 



Monadic Argument Domain 



Type 


Character 


Shape 


Vector domain or one-row matrix 


Depth 


or l (simple) 


Dyadic Left Argument Domain 


Type 


Near-integer 


Shape 


Vector domain 


Depth 


or l (simple) 


Dyadic Right Argument Domain 


Type 


Character 


Shape 


Matrix domain 


Depth 


or l (simple) 


Result Domain 




Type 


Boolean (dyadic) or integer (monadic) 


Rank 


l 


Shape 


Vector 


Depth 


l (simple) 
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Description 

OS TOP allows you to suspend the execution of user-defined operations at 
specified lines. DSTOP is a useful debugging tool; you can use it to execute 
a portion of a user-defined operation, then to stop execution temporarily and 
examine the operation's environment, including the values of its local variables. 
You can also stop execution at fine 1 of an external routine. 

The external image containing the external routine must be linked with 
the /SHARE and /DEBUG qualifiers; APL causes VMS DEBUG to set a 
breakpoint at line 1 (the routine entry point). 

For dyadic USTOP, the right argument identifies the operations you want to 
suspend. Each row should be the name of a valid, unlocked, user-defined 
operation or an external routine. 

The left argument specifies where you want to suspend the operations by 
naming the lines on which stop bits are to be set; the line numbers do not have 
to be in order. Negative line numbers and line numbers that do not appear in 
the operation are ignored. 

Note that line [0] can be stopped; APL suspends execution immediately 
before returning to the caller, thus enabling you to examine the operation's 
environment after it has finished executing. 

The following example sets a stop bit at lines [5], [25], and [55] of the user- 
defined operations CALC and AVER: 

5 25 55 USTOP 2 Up ' CALCAVER' 
1 1 

Thus, if you run CALC or AVER, execution is suspended before line [5], and APL 
displays the operation name and the line number. Execution can be resumed if 
you type a branch to line [5], but it is suspended again at line [25], and so on. 

The result of dyadic DSTOP is a Boolean vector that indicates whether stop bits 
were set for the objects named. A 1 in the position corresponding to the name 
in the right argument indicates that the stop bits were successfully set; a 
indicates that stop bits were not set. 
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To clear all the stop bits associated with an object or objects, use USTOP with 
an empty left argument, as follows: 

(i 0) USTOP 2 Up 'CALCAVER* 

1 1 

If you modify an operation with )EDIT, DFX, or UMAP, you clear any stop bits 
set with USTOP. (However, you can view an operation with )EDIT and not 
clear the stop bits as long as you do not perform any modifications.) If you edit 
an operation with the A editor, stop bits remain on existing lines (provided 
they are not modified) even if the lines are renumbered when the operation is 
closed. 

When operation execution is suspended because a stop bit was set for the line, 
APL signals ST OP SET. Thus, you can trap stop bits with D TRAP. 

In its monadic form, USTOP returns the line numbers (in ascending order) on 
which stop bits have been set for a specified operation. The right argument 
must contain only one row, which identifies the name of the operation. In the 
case of a stop bit that is set on an external routine, Q STOP returns a one-item 
vector with a value of 1 (the only allowable line). For example: 

USTOP 'CALC 
5 25 55 

If the argument is empty or contains a value other than the well-formed name 
of an unlocked operation, APL returns an empty Boolean vector. 

For more details about USTOP, see Chapter 3 in the VAX APL User's Guide. 

Possible Errors Generated 

Dyadic Form 

9 RANK ERROR (NOT MATRIX DOMAIN) 

9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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Monadic Form 

9 RANK ERROR (NOT MATRIX DOMAIN) 

10 LENGTH ERROR 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 
15 DOMAIN ERROR (INCORRECT TYPE) 
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D TERSE Terse Error Messages 
Type 



System Variable 




Form 






D TERSE f 


terse-verbose 


integer- scalar «- 


D TERSE 


Value Domain 






Type 




Near-integer 


Shape 




Singleton 


Depth 




or l (simple) 


Value 




or l 


Default 








Result Domain 



Type 


Integer 


Rank 





Shape 


i o (scalar) 


Depth 


(simple scalar) 


Description 





Each APL error message (see Appendix A) consists of a primary error message 
(for example, VALUE ERROR or DOMAIN ERROR) and perhaps a secondary error 
message. The secondary message provides more information about why the 
error occurred. 

D TERSE determines whether or not secondary error messages are output. 
When D TERSE is 0, secondary error messages are printed; when it is 1, they 
are not printed. The default is 0. 

Note that APL always puts secondary error messages into □ ERROR, regardless 
of the value of D TERSE. 

The value of D TERSE is saved when you save the active workspace and can be 
localized in user-defined operations. 
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Possible Errors Generated 

9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (NOT SINGLETON) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

15 DOMAIN ERROR (SYSTEM VARIABLE VALUE MAY ONLY BE OR 1) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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D TIMELIMIT User Response Time Limit 
Type 

System Variable 

Form 

QTIMELIMIT *■ seconds 
integer-scalar *■ QTIMELIMIT 



Value Domain 




TVpe 


Near-integer 


Shape 


Singleton 


Depth 


or l (simple) 


Value 


" 1 to 2 5 5 


Default 


(unlimited response time) 


Result Domain 




Type 


Integer 


Rank 





Shape 


i (scalar) 


Depth 


(simple scalar) 


Description 





D TIMELIMIT limits the amount of time allowed for responses to quote quad 
(0 ) or quad del (0 ) input requests. Note that you cannot set □ TIMELIMIT on a 
VT220, VT240, VT320, VT330, VT340, or DECterm terminal designator. 

If, in responding to input requests, you exceed UTIMELIMIT seconds between 
characters, APL accepts only the characters you typed before you ran out of 
time, and appends a <CRxLF> to them. You can use the D TIMEOUT system 
variable to check whether the time limit expired. 

In the following example, the user sets the time limit to 5 seconds, and then 
supplies a value for A before the time limit expires. However, the user does 
not finish entering a value for B before time expires, so APL accepts what was 
typed before time ran out. The six spaces after the last character (an angle 
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□ TIMELIMIT User Response Time Limit 

bracket) are APL's input prompt, and the comment (a 6 SPACES IS PROMPT) is 
terminal input. 

UTIMELIMIT+5 

YOU HAVE FIVE SECONDS 

A 
YOU HAVE FIVE SECONDS 

NOW STOP TYPING BUT NO <RETURN> 

nTIMELIMIT WAS EXCEEDED ON PREVIOUS LINE 
B 
NOW STOP TYPING BUT NO <RETURN> 

A negative argument (~ 1) makes APL check for type-ahead input, that is, data 
that was placed in the input buffer before the quote quad or quad del input 
request was made. You can use this feature to help you determine whether 
anything was typed after the time limit expired. For example: 





VTIME 


[1] 


UTIMELIMIT^S 


[2] 


D«-' RESPOND WITHIN 5 SECONDS 1 


[3] 
[4] 


A+B 

U^' TIMED OUT' o USINK+UDL 5 


[5] 


UTIMELIMIT*-~1 


[6] 
[7] 


B+0 

A,' BEFORE TIMED OUT AND ' ,B 


[8] 


V 
TIME 



pi DM DELAYS EXECUTION 



AFTER < 



RESPOND WITHIN 5 SECONDS 
I STOPPED TYPING 

TIMED OUT 

THIS IS TYPEAHEAD 

I STOPPED TYPING BEFORE TIMED OUT AND THIS IS TYPEAHEAD AFTER 

Because □ TIMELIMIT was set to ~~ 1 on line [5], the quote quad request on line 
[6] captured the input that was typed after time expired on the response to the 
first quote quad input request (line [3]), but before the second input request 
(line [6]) was made. 

You may also want to set D TIMELIMIT to ~ 1 if you have written a function 
that checks periodically for a response to a poll or prompt. For example: 
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V POLL; START 

[1] UTIMELIMIT^'l 

[2] B+<MEN READY TYPE THE NUMBER 1 ' 

[3] USINK*UDL 5 RDM DELAYS EXECUTION 5 SECONDS 

[4] STMr-H!] 

[5] ->■( START = 'l')/7 

[6] +3 

[7] ^EXECUTION BEGINS HERE 

[8] v 

POLL 
WHEN READY TYPE THE NUMBER 1 l 

The function POLL displays a message telling the user to respond with the 
number 1 when ready. Until the user enters 1, POLL loops between operation 
lines [3] and [6]; thus, POLL delays for 5 seconds, then checks whether the user 
typed 1 during the delay and, if not, branches back for another 5-second delay. 
When the user enters 1, control passes to line [7] and operation execution 
continues. 

The value of UTIMELIMIT is saved when you save the active workspace and 
can be localized in user-defined operations. 

Possible Errors Generated 

9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (NOT SINGLETON) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

15 DOMAIN ERROR (PARAMETER OUT OF RANGE) 

15 DOMAIN ERROR (TIMEOUT READ UNSUPPORTED FOR CURRENT VALUE OF 
QUAD TT) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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D TIMEOUT Time Limit Report 
Type 



System Variable 



Form 



□ TIMEOUT «- 0- 


or-1 


integer-scalar ■*- 


D TIMEOUT 


Value Domain 




Type 


Near-integer 


Shape 


Singleton 


Depth 


or l (simple) 


Value 


or l 


Default 






Result Domain 



Type 


Integer 


Rank 





Shape 


i o (scalar) 


Depth 


o (simple scalar) 


Description 





D TIMEOUT queries the system to see whether response time expired for a 
previously executed quote quad (Q) or quad del (0) input request. (D TIMEOUT 
is set implicitly by the system when a timeout occurs, but can also be set by 
the user.) Its value is a Boolean scalar \ 1 means that time ran out, means 
that it) did not. The amount of time the user has to respond to quote quad or 
del quad input requests is determined by the Q TIMELIMIT system variable. 
For example: 
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QTIMELIMIT+5 

YOU HAVE FIVE SECONDS 

UTIMEOUT aDID NOT RUN OUT OF TIME 



A+-E 
NOW STOP TYPING BUT NO <RETURN> 

UTIMEOUT nTIMELIMIT EXCEEDED 

1 

You may set □ TIMEOUT to or l . APL changes the value of D TIMEOUT only 
when you type one of the following: 

• Quote quad input from the terminal (Q ) 

• Quad del input from the terminal (0 ) 

The value of Q TIMEOUT is saved when you save the active workspace and can 
be localized in user-defined operations. 

Possible Errors Generated 



9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (NOT SINGLETON) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

15 DOMAIN ERROR (SYSTEM VARIABLE VALUE MAY ONLY BE OR 1) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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□ TLE Terminal Line Editing Characteristics 
Type 



System Variable (session) 


Form 




DTLE ■*■ Q-or-1 




current-value ■*■ 


DTLE 


Value Domain 




Type 


Near-Integer 


Shape 


Singleton 


Depth 


or l (simple) 


Value 


o or l 


Default 


Determined when APL is invoked 



Result Domain 



Type 


Integer 


Rank 





Shape 


i o (scalar) 


Depth 


o (simple scalar) 


Description 





D TLE controls the terminal line editing attribute. You can assign a or a 1 to 
D TLE. By default, D TLE inherits the line editing status that is in effect when 
APL is started. Note that Q TLE is a session variable; that is, its value is not 
saved with the workspace and Q TLE is not reset by the execution of a ) CLEAR 
command (see Chapter 3). 

D tle Equivalent DCL Command 

$SET TERMINAL/NOLINE_EDITING 

1 $SET TERMINAL/LINE_EDITING 

APL determines the default value for DTLE depending on your terminal 
designator. For LA, VT102, GIGI, KEY, BIT, HDS201, and HDS221 (terminals 
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D TLE Terminal Line Editing Characteristics 

that form overstruck characters with the Backspace key), the default is 0. For 
VT220, VT240, VT320, VT330, VT340, DECterm and VS (terminals that form 
overstruck characters with the Compose key or Ctrl/D), the default is 1. In 
all other cases (TTY for example), the default is the same as the current VMS 
setting when APL is invoked. 

Possible Errors Generated 



9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (NOT SINGLETON) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

15 DOMAIN ERROR (SYSTEM VARIABLE VALUE MAY ONLY BE OR 1) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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D TRA CE Monitoring Operation Execution 
Type 

Ambivalent System Function 

Form 

line-numbers ■*■ Q TRACE function-name 

success I fail *■ line-numbers D TRACE function-name 



Monadic Argument Domain 



Type 


Character 


Shape 


Vector domain or 1-row matrix 


Depth 


or l (simple) 


Dyadic Left Argument Domain 


Type 


Near-integer 


Shape 


Vector domain 


Depth 


or l (simple) 


Dyadic Right Argument Domain 


Type 


Character 


Shape 


Matrix domain 


Depth 


o or l (simple) 


Result Domain 




Type 


Integer (dyadic) or Boolean (monadic) 


Rank 


l 


Shape 


Vector 


Depth 


l (simple) 
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Description 



D TRA CE is a debugging tool that allows you to obtain intermediate results of 
operation execution. 

In the dyadic form, the right argument identifies the operations that you 
want to trace. Each row should be the name of a valid, unlocked, user-defined 
operation. You can also specify the name of an external routine. 

The left argument specifies the line numbers you want to trace. The line 
numbers do not have to be in order. Negative line numbers and line numbers 
that do not appear in the operation are ignored. When you trace line of 
an operation, APL displays the result returned by the operation before the 
operation exits. For external routines, you can specify only line 0. 

When you execute a line of an operation that has the trace bit set, APL 
displays the following information: 

• The name of the operation 

• The line number being traced (always for external routines) 

• The final value returned by the statement, provided that the value is not 
an enclosed array, in which case APL displays a message indicating an 
enclosed value 

When the statement traced is not the first statement on the line, APL also 
displays the statement number. 

The result of dyadic Q TRACE is a Boolean vector that indicates whether trace 
bits were set for the operations named. A 1 in the position corresponding to 
the name in the right argument indicates that the trace bits were successfully 
set; a indicates that trace bits were not set. 

To clear all the trace bits associated with an object or objects, use D TRA CE with 
an empty left argument, as follows: 

(i0) UTRACE 2 kp'CALCAVER' 
1 1 

If you modify an operation with )EDIT, UFX, or UMAP, you clear any trace 
bits set with Q TRACE. (However, you can view an operation with )EDIT and 
not clear the trace bits as long as you do not perform any modifications.) If 
you edit an operation with the A editor, trace bits remain on existing lines 
(provided they are not modified), even if the lines are renumbered when the 
operation is closed. 
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In the monadic form, D TRACE returns the line numbers (in ascending order) 
on which trace bits are set for a specified operation. The right argument must 
contain only one row, which identifies the name of the operation. In the case of 
a trace bit that is set on an external routine, D TRA CE returns a one-item vector 
with a value of (the only allowable line). The result indicates the lines that 
exist and have trace bits set on them. For example: 

QTRACE 'CALC nLISES 5, 25, AND 55 ARE TRACED 
5 25 55 

If the argument is empty or contains a value other than the well-formed name 
of an unlocked operation, APL returns an empty Boolean vector. 

For more details about a TRACE, see the VAX APL User's Guide. 

Possible Errors Generated 

Dyadic Form 

9 RANK ERROR (NOT MATRIX DOMAIN) 

9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
Monadic Form 

9 RANK ERROR (NOT MATRIX DOMAIN) 

10 LENGTH ERROR 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 
15 DOMAIN ERROR (INCORRECT TYPE) 
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□ TRAP Trap Expression 
Type 



System Variable 




Form 






UTRAP +- terminal-type 
current-value *- Q TRAP 


Value Domain 






Type 

Shape 

Depth 

Default 




Character 
Vector Domain 
o or l (simple) 

i i 



Result Domain 



Type 


Character 


Rank 


l 


Shape 


Vector 


Depth 


l (simple) 


Description 





D TRAP allows you to override a system response with a user-defined response. 
The value of Q TRAP is a character vector representing an APL expression. 
This expression is executed (in t fashion) when any of the events listed in 
Appendix A are signaled during the execution of a user-defined operation. This 
includes an attention signal, an abort input signal, or a stop bit (USTOP). For 
information on error handling, see the VAX APL User's Guide. 

You can set Q TRAP as a global variable or localize it in an operation. When an 
error occurs during execution of a user-defined operation, APL searches for the 
most local D TRAP. If Q TRAP is set to anything other than the empty vector (the 
default value), APL executes it in the envirnoment of the operation where the 
error occurred. For example: 
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V R-.UTRAP 
[1] 0TRAP+- <+L< 
[2] A+5 
[3] fl^O 
[4] C+A+B 

[5] ^DIVISION Bl IS DOMAIN ERROR 

[6] L: 'TRAPPED ERROR, THEN CONTINUED' 
[7] 'EXECUTED LAST LINE' V 

R 
TRAPPED ERROR, THEN CONTINUED 
EXECUTED LAST LINE 

)SI 

UERROR 
15 DOMAIN ERROR [DIVISION BY ZERO) 
RW C*-AtB 

A 

The following example shows what happens when Q TRAP is not set: 
vc 

[1] A+5 
[2] fl-K) 
[3] C+A + B V 
G 
15 DOMAIN ERROR (DIVISION BY ZERO) 
ff[3] C+A+B 

A 

)SI 
ff[3] * 

If execution of an operation's □ TRAP expression does not transfer control to 
a new statement, the operation becomes suspended. If such an operation is 
a locked operation, APL cuts back the state indicator to the first unlocked 
operation and then signals DOMAIN ERROR (UNSUCCESSFUL TRAP IN LOCKED 
FUNCTION). 

Because a TRAP expression can call an operation, you may want to localize 
□ TRAP in the called operation and set Q TRAP to ' ' to avoid unwanted loops. 

Possible Errors Generated 



9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (UNSUCCESSFUL TRAP IN LOCKED FUNCTION) 
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□ TS Time Stamp 
Type 

Niladic System Function 

Form 

current-time I date <- QTS 

Result Domain 



Type 


Integer 


Rank 


l 


Shape 


7 


Depth 


l (simple) 



Description 

D TS (time stamp) returns a vector (in base 10 format) representing the current 
time and date. This vector is known as a time stamp and contains the current 
year, month, day, hour, minute, second, and millisecond. 

For example: 

UTS R21-N0V-90 11:31:55.131* 

1990 11 21 11 31 55 134 

Possible Errors Generated 

None. 
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□ TT Terminal Type 



Type 



Form 



System Variable (session) 



D TT *■ terminal-type 
integer-scalar *■ Q TT 


Value Domain 




Type 

Shape 

Depth 

Value 

Default 


Near-integer 

Singleton 

or l (simple) 

o through 19 

Determined when APL is invoked. 


Result Domain 




Type 
Rank 


Integer 




Shape 
Depth 


i (scalar) 

o (simple scalar) 



Description 

D TT (terminal type) indicates the type of terminal being used for the current 
APL session. When you invoke APL, you specify the terminal type in an 
initialization stream or in response to the terminal designator prompt. 

D TT allows you to change the terminal type during an APL session. The 
following table shows the possible values and meanings for D TT: 
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□ TT Terminal Type 



D tt Values 
Value Meaning 



1 APL COMPOSITE terminal 

2 TTY-type terminal 

3 Digital VK100 (GIGI) terminal (key-paired) 

4 Digital LA-type terminal (key-paired) 

5 APL/ASCII key-paired terminal 

6 APL/ASCII bit-paired terminal 

7 Digital VAXstation running VWS(composite) 

8 Digital VT102 (key-paired) 

9 Digital VT220 (key-paired) 

10 Digital VT240 (key-paired) 

11 Tektronix 4013 terminal (key-paired) 

12 Tektronix 4015 terminal (key-paired) 

13 HDSAVT (key-paired) 

14 HDS201 (key-paired) 

15 HDS221 (key-paired) 

16 Digital VT320 (key-paired) 

17 Digital VT330 (key-paired) 

18 Digital VT340 (key-paired) 

19 Digital VAXstation running DECwindows (key-paired) 



You can query for the current UTT value by entering D TT without assigning a 
value. APL responds with the current value. For example: 

$apl/term=decterm /silent=all 

UTT 
19 

If you specify APL as your terminal designator when you first invoke APL, D TT 
is set to 5 . You can change the value of D TT by assigning it a valid terminal 
type. For example: 

1 10 ^TERMINAL DESIGNATOR IS APL 

123456789 10 

UTT <- 2 

.iolO "The terminal type is now TTY 
123456789 10 
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If you change the value of □ TT, APL may send an escape sequence to the 
terminal to change its character set. This escape sequence is the same as the 
one that is sent after you identify the terminal when invoking APL. 

If the value of QTT is currently 9, 10, 16, 17, 18 or 19 and you leave the APL 
environment temporarily (with a )DO, )EDIT, or )PUSH command), you should 
be careful about changing your terminal type while at the operating system 
level. If you return to APL with a different terminal type, or if the font files for 
the APL character set are not available, APL signals an error. (You also get an 
error if you restricted access to those files while at the DCL level.) 

Note that D TT is a session variable; that is, its value is not saved with the 
workspace and D TT is not reset by the execution of a ) CLEAR command (see 
Chapter 3). However, it can be localized in user-defined operations. 

Possible Errors Generated 



9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR (NOT SINGLETON) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (ERROR ACTIVATING IMAGE) 

15 DOMAIN ERROR (FONT FILE COULD NOT BE OPENED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (NEGATIVE INTEGER NOT ALLOWED) 

15 DOMAIN ERROR (NOT AN INTEGER) 

15 DOMAIN ERROR (PARAMETER OUT OF RANGE) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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□ UL User Load 




Type 




Niladic System 


Function 


Form 




pid *- Q UL 




Result Domain 




Type 


Integer 


Rank 





Shape 


i (scalar) 


Depth 


(simple scalar) 


Description 





The result of D UL (user load) represents the user's process identification 
number (PID). VMS assigns you a unique PID each time you log in to the 
system. If you log off and then log back in to VMS, your PID (and thus, your 
D UL value) probably will have changed. For example: 



UUL 
93 

You can use the following expression to convert a PID from decimal, as it 
appears in the APL environment, to hexadecimal, as it appears in the DCL 
environment: 

1 012 3t567 890i4BCDEF '[DI0+(8p 16 )tOM] 
00000055 

Possible Errors Generated 

None. 
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□ VERSION Interpreter and Workspace Version 
Type 



Niladic System Function 


Form 




version-info ■*- 


D VERSION 


Result Domain 




Type 


Character 


Rank 


l 


Shape 


Vector 


Depth 


l (simple) 


Description 





D VERSION returns a two-row character vector, with each row followed by a 
<CRxLF>. The first row identifies the version of the interpreter under which 
the current workspace was saved; the second row identifies the version of the 
interpreter that is currently running. The display is in the form Iv.u-edit, 
where I is the support letter, v is the version number, u is the update number, 
and edit is the edit number. For example: 

UVERSION 
73.2-834 
73.2-834 

Possible Errors Generated 

None. 
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D VI Validating Input 
Type 

Monadic System Function 

Form 

valid I invalid-number *■ □ VI character-vector 

Argument Domain 



Type 


Character 


Shape 


Vector domain 


Depth 


l (simple) 


LiOlTlain 

Type 


Boolean 


Rank 


l 


Shape 


Vector 


Depth 


1 (simple) 



Implicit Arguments 

D NG (controls negative number recognition) 

Description 

D VI determines the valid numbers in a character argument. D VI examines 
fields in the argument that are delimited by one or more spaces, tabs, or a 
carriage return (optionally followed by a line feed), and returns a Boolean 
vector that contains a 1 in each position corresponding to a field containing a 
valid number, and a in each position corresponding to an invalid number. If 
the argument is empty, Q VI returns an empty array. 

D VI is often used in conjunction with D FI and the compression function 
(see Section 1.3.1) to select the valid numbers from a character string; □ VI 
produces the left argument of the compression function, and Q FI produces the 
right argument. For example: 
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4<-'1.5 3 A "5 3. . 1.0E +1 "3' 

UVI A 
11010001 

QFI A 
1.5 3 5 3 

(UVI A) /QFI A 
1.5 3 5 3 

Recognition of negative numbers in the Q VI argument depends upon the value 
of the system variable Q NG. If Q NG equals 1 (the default), negative numbers in 
the D VI argument must begin with the high minus sign (~ ) to be recognized. 
If QNG equals 0, numbers preceded by a minus sign (- ) are recognized as 
negative numbers. If UNG equals 2, negative numbers are preceded by an 
APL "+" symbol. (APL "+" prints as an ASCII "-" so DNG_2 can be used to 
handle negative numbers in strings that will be read or written In ASCII.) For 
example: 

UNG+1 a" MEANS NEGATIVE 

X<-'66 G "7 +9 -4' 

UVI X 
10 10 

QNG+0 q- MEANS NEGATIVE 

UVI X 
10 1 

DM>2 fl+ MEANS NEGATIVE 

UVI X 
10 10 

Note that the case where D NG is may be useful when you use APL to 
interpret data created by other languages, specifically those that do not use the 
high minus sign (~ ). 

Possible Errors Generated 



9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 
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D VPC Vector Process Control 
Type 

System Variable (session) 

Form 

Q VPC +■ session variable 
integer-scalar ■*- QVPC 

Value Domain 

Type Non-negative near-integer 

Shape Singleton 

Depth o or l (simple) 

Default Determined when APL is invoked. 

Result Domain 



Type 


Integer 


Rank 





Shape 


i (scalar) 


Depth 


(simple scalar) 


Description 





D VPC determines the threshold at which vector processing is used. A value of 
indicates that vector processing is not used; a value of 1 indicates that the 
vector processing is always used. 

When you invoke a session, APL determines whether a vector processor is 
available. □ VPC is set to if no vector processor is available; it is set to the 
non-negative, near-integer default if a vector processor is available. You can 
also specify the value for □ VPC when you invoke an APL session with the 
qualifier /|[NOIVECTOR=n (see the section on initializaiton streams in the 
VAX APL User's Guide). 

If a vector processor is not present, setting D VPC to a non-zero value results in 
the use of the vector processer emulator. The vector processer emulator may 
be useful for testing. The vector processer emulator should not be used for 
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D VPC Vector Process Control 

applications because APL's performance with the emulator is usually poorer 
than APL's performance with the scalar processor. 

D VPC is a session variable; that is, its value is not saved with the workspace, 
and D VPC is not reset by the execution of a ) CLEAR command (see Chapter 3). 
However, it can be localized in user-defined operations. 

You can query for the current Q VPC value by entering D VPC without assigning 
a value. APL responds with the current value. For example: 

Uvpc 

30 

Controlled testing can help you identify the threshold at which the increased 
overhead of running the vector processer is compensated for by increased 
performance. 

Possible Errors Generated 



9 RANK ERROR {NOT SINGLETON) 

15 DOMAIN ERROR {NEGATIVE NUMBER NOT ALLOWED) 

15 DOMAIN ERROR {NOT AN INTEGER) 

15 DOMAIN ERROR { VECTOR PROCESSOR NOT AVAILABLE) 
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D VR Visual Representation 
Type 

Monadic System Function 



Form 




D VR {value 1 


object-name} 


Argument Domain 




Type 


Any 


Shape 


Any 


Depth 


Any 


Result Domain 




Type 


Character 


Rank- 


Any 


Shape 


Any 


Depth 


Any 



Implicit Arguments 

QDC (Controls display of enclosed arrays) 

D PP (Controls precision of numeric constants) 

Description 

Q VR returns a character array of the visual representation of an APL object. 
The argument is either a numeric array of any rank or a character array with 
its shape in the vector domain. 

If the argument is numeric, Q VR works the same way as monadic ? : the 
numeric array is formatted into a character array that looks as the numeric 
array would appear when displayed by APL (which is dependent on the D PP 
setting). 
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If the argument is type character, its value must represent the name of an APL 
object. If the character argument represents a variable or label, the result is 
the same as for numeric arguments: APL formats the variable or label value 
as a character array, making it look as it would appear when displayed by 
APL. 

If the character argument represents a user-defined operation, Q VR returns 
a character vector that is similar to the canonical representation of the 
operation. Specifically, the visual representation of a user-defined operation, 
F , is the operation definition displayed by the editor command A F [ Q ] A . The 
result starts and ends with a A character, and each line begins with a line 
number surrounded by square brackets and ends with a <CRxLF>. 

If the character argument represents a derived function such as an operand 
of a user-defined operator, Q VR returns a character representation of it. For 
example, if the operand is plus (+ ), then D VR returns the string ' + ' ; if the 
operand is outer product (+.*), then Q VR returns ' + .*'; and if the operand is 
D CR, then □ VR returns ' D CR ' , 

If the argument to D VR is empty, the result is an empty character vector. 

Examples: 

aCREATE FUNCTION FRTH 

VZ «- A FRTH B; X 
[1] L: Z <- A + B V 

)FNS 
FRTH 

D<-7+-2 3pi6 aCREATE AND DISPLAY V 

1 2 3 
4 5 6 

pV 

2 3 

Q<-A+ftVR <V< 
12 3 
H 5 6 

PA 
2 5 

D<-B«-DW? 'FRTH' 

VZ «- A FRTH B; X 
[1] I: Z *■ A + B 



51 
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Possible Errors Generated 

9 RANK ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (OPERATION LOCKED) 
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D VIA Workspace Available 
Type 



Niladic System 


Function 


Form 




available- space 


i- UNA 


Result Domain 




Type 


Integer 


Rank 





Shape 


i (scalar) 


Depth 


(simple scalar) 


Description 





D WA (workspace available) returns an integer scalar representing an estimate 
of the amount of available storage space, in bytes, in the active workspace. 
This value allows you to determine the maximum amount by which your 
workspace can increase. APL obtains the value by subtracting the current 
data-segment size from the maximum data-segment size which is the current 
)MAXCORE setting (see Chapter 3). Thus, the value returned by Off A may 
be greater than the amount of available memory or the amount of memory 
allocated by APL. For example: 

QUA 
516980 

Possible Errors Generated 

None. 
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□ WA IT Limiting Time on Read Functions 
Type 

Ambivalent System Function (dyadic form is quiet) 

Form 

current -timelimit *■ UWAIT charts 
i o +- timelimit UN AIT chart 



Monadic Argument Domain 



Type 


Near-integer 




Shape 


Vector domain 




Depth 


or l (simple) 




Value 


~ 9 9 9 through 9 9 9 


(but not ) 


Left Argument Domain 




Type 


Near-integer 




Shape 


Singleton 




Depth 


o or l (simple) 




Value 


~ l through 2 5 5 (seconds) 


Right Argument Domain 




TVpe 


' Near-integer 




Shape 


Singleton 




Depth 


o or l (simple) 




Value 


"999 through 999 


(but not o ) 



APL Reference Manual 2-211 



System Variables and Functions 
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Result Domain 



Type 


Integer 


Rank 


l 


Shape 


Vector 


Depth 


l (simple) 


Description 





Dyadic UWAIT specifies the amount of time you want APL to wait when it tries 
to read a shared record that is locked by another user. 

When you set a waiting period, APL waits even if you specified the 
/ READONLY -.NOLOCKS qualifier when you assigned the file to a channel 
with BASS (NO LOCKS normally causes a read to happen without waiting). 

The left argument (timelimit) determines the time limit; it has the following 
meanings: 

Value of Time Limit Meaning 

~ l Don't wait, return immediately 

Wait indefinitely (this is the default) 

n Wait for n seconds 

Monadic UWAIT queries the system for the current time limits associated with 
individual channel numbers. 

For each channel number in the argument, monadic UWAIT returns a value 
between ~~ l and 2 5 5 that can have the following meanings: 

Value Returned Current Time Limit 

~ l Don't wait 

o Wait indefinitely 

n Wait for n seconds 

UWAIT is described in the VAX APL User's Guide along with other file I/O 
information. 
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Possible Errors Generated 

Monadic Form 

1 FILE NOT FOUND {FILE NOT FOUND) 
10 LENGTH ERROR (NOT VECTOR DOMAIN) 

15 DOMAIN ERROR (ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (INVALID CHANNEL NUMBER) 

15 DOMAIN ERROR (NOT AN INTEGER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
Dyadic Form 

1 FILE NOT FOUND (FILE NOT FOUND) 
10 LENGTH ERROR (NOT SINGLETON) 
15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (NOT AN INTEGER) 

15 DOMAIN ERROR (PARAMETER OUT OF RANGE) 

15 DOMAIN ERROR (INVALID CHANNEL NUMBER) 

15 DOMAIN ERROR (CHANNEL NOT ASSIGNED) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 

3 3 10 ERROR (TIMEOUT PERIOD EXPIRED) 
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D WA TCH Monitoring Variable Changes 
Type 

Ambivalent System Function 

Form 

currentmode ■*- Q WATCH object-name 

success I failure mode-number Q WATCH object-names 



Monadic Argument Domain 



Type 


Character 


Shape 


Vector domain or one-row matrix 


Depth 


o or l (simple) 


Dyadic Left Argument Domain 


Type 


Near-integer 


Shape 


Vector domain 


Depth 


o or l (simple) 


Dyadic Right Argument Domain 


Type 


Character 


Shape 


Matrix domain 


Depth 


or l (simple) 


Result Domain 




Type 


Integer 


Rank 


l or 2 


Shape 


Vector or matrix 


Depth 


l (simple) 
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Description 

WATCH is a debugging tool that allows you to monitor changes in the value 
of APL objects. APL either displays or signals information when a watched 
object is referenced or modified. You can set watch modes on variable and label 
names and most system variables and niladic system functions. You cannot set 
watch modes on nonniladic system functions, ill-formed identifiers, user-defined 
operations, or group names. A watch mode remains in effect when the watched 
object occurs in a locked operation; the watch bit is not reset, as is the case 
with D STOP and Q TRACE. 

A modification occurs any time a value is explicitly assigned to a variable 
(niladic system functions and labels cannot be modified). A reference occurs 
any time an object is referenced for its value. 

In display mode, APL sends information to the current output and continues 
execution of the operation where the reference or modification occurred. In 
signal mode, APL signals an error (trappable with OTRAP) and suspends the 
operation. 

Implicit in the use of the D WATCH command are the DI and OR system 
variables. Each time a modification occurs on a watched object, APL reassigns 
the values of these variables: D£ contains the name of the changed object; OR 
contains the previous value of the changed object. The object contains the new 
value. 

Dyadic WATCH enables watchpoints on one or more objects. The right 
argument specifies the objects you want to watch. Each row contains the 
name of one niladic system function or one variable (which can be a defined 
or undefined variable), a system variable, or a label. You cannot watch the 
following system variables: OR, OL, or ERROR. If the right argument is empty, 
or if it contains the name of an object that cannot be watched, APL returns an 
empty Boolean vector. 

The left argument determines the watch mode: either display or signal 
mode. In addition, you can specify the watch mode for either modifications or 
references. 
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There are six watch modes: 



Mode Meaning 



2 Signal if modified 

3 Display if modified 

4 Signal if referenced 

5 Display if referenced 

6 Signal if modified or referenced 

7 Display if modified or referenced 

The result of dyadic U WATCH is a Boolean vector indicating whether the 
watch mode was set for the specified variables. Each position in the vector 
corresponds to a row of the right argument. A 1 indicates that the watch 
mode was successfully set; a indicates that the watch mode was not set. For 
example: 

B *■ 3 5 p 'BABELSABLECABLE' 

B 
BABEL 
SABLE 
CABLE 

1 WATCH B 
1 1 1 

To clear the watch mode associated with an object or objects, use dyadic 
□ WATCH with an empty left argument. The result is a Boolean vector 
indicating whether the watch mode was turned off. Each position in the 
vector corresponds to a row of the right argument. A 1 indicates the watch 
mode was successfully turned off; a indicates the watch mode was not turned 
off. For example: 

" WATCH 3 5 p 'BABELSABLECABLE' 
1 1 1 

In signal mode, you can trap a reference or modification with DTRAP. APL 
signals a primary message and one of three secondary messages. The signals 
have the following form: 

113 WATCH POINT ACTIVATED ( VARIABLE HAS BEEN REFERENCED) 

113 WATCH POINT ACTIVATED ( VARIABLE HAS BEEN MODIFIED) 
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113 WATCH POINT ACTIVATED ( VARIABLE HAS BEEN MODIFIED BY INDEX) 

In display mode, APL displays information in different forms depending on 
whether the event is a reference or a modification. For a reference, the display 
form is as follows: 

function-name [line o statement] object-name 

OLD name class-, nc SHAPE: rho-vector 
value 

For a modification, the display form is as follows: 

function-name I line o statement] object-name 

OLD NAME CLASS: nc SHAPE: rho-vector 

value 

NEW NAME CLASS: nc SHAPE: rho-vector 

value 

Note that if value is an enclosed array, APL does not display the value. 
Instead, APL displays a message indicating that value is enclosed. 

If the operation that contains the reference or modification is locked, APL 
displays the name of the object with a protected del (f ) symbol (there is no line 
number). 

Monadic Q WATCH returns information indicating the current watch mode for 
the object specified in the right argument. The right argument must have at 
most one row, which means you must query for the watch mode one object at a 
time. 

The result of monadic WATCH is a one-element integer vector (unless the 
argument is empty, in which case APL returns i ). There are seven possible 
values which indicate the following watch modes: 

Mode Meaning 

1 Object not being watched 

2 Signal if modified 

3 Display if modified 

4 Signal if referenced 
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Mode Meaning 



5 Display if referenced 

6 Signal if modified or referenced 

7 Display if modified or referenced 



When D WATCH is set in mode 2 or 6 on a name that is the left argument 
of a strand assignment, the signal is delayed until APL has completed 
all the assignments. If there is more than one watched name in the left 
argument, APL only signals information on the last (rightmost) one. (For more 
information, see the strand assignment sections in Chapter 1.) 

Some events do not activate a Q WATCH signal or display (immediate mode 
events, for example). In addition, a watchpoint is not activated when the 
following occur: 

• A variable is used as an output parameter in a call to an external function. 

• An object becomes shadowed by an operation invocation. 

• An object becomes unshadowed by an operation termination. 

• A variable is included in the argument of any of the following commands: 

QEX, ) ERASE, )COPY, )PCOPY, DQCO, and Q QPC. 

When you enable D WATCH, the watchpoint is set on the most local version 
of the specified objects. When a watched object becomes shadowed, APL 
saves the current D WATCH definition and restores it when the object becomes 
unshadowed. Labels are always local to an operation and are defined only 
when the operation is being executed. To watch the referencing of a label, 
you must enable D WATCH within the context of the operation (either inside the 
operation or in immediate mode while the operation is suspended or pending). 
(The VAX APL User's Guide has more information on debugging operations.) 
An example of this behavior follows: 

X+5 aDEFINE GLOBAL X 

3 QSfATCH 'X' ^ENABLE WATCHPOINT ON X 
1 

VSHAG1-.X rDEFINE LOCAL X 

[1] D*-X<-1 ^SIMPLE ASSIGNMENT 
[2] V 

SHAGl aCALL TO SRAGl, LOCAL X SHADOWS GLOBAL X 
1 

fl/VO QWATCH EVENT OCCURS 
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This same behavior occurs when a local variable becomes shadowed by a more 
local variable: 





VSHAGl-X 




aRE~WRITE SHAG1 


[1] 


D^+l 






[2] 


3 QWATCH 'X' 




^ENABLE WATCHPOIHT OH LOCA 


[3] 


SHAG2 




nCALL SHAG2 


[4] 


V 








V SHAG2;X 




9.ADD ANOTHER LOCAL X 


[1] 


Q+X+2 




aSIMPLE ASSIGNMENT 


[2] 


V 








SHAG1 




nEXECUTE SHAG1 


1 


(Value 


0/ 


local X in SHAG1) 


2 


( SHAG2 


Jocai I shadows SHAG1 local X 



Examples: 



F +■ 5 
3 WATCH 



F 



nDEFINE GLOBAL F 

^ENABLE DISPLAY IF MODIFIED 



1F00 
[1] F *■ i9 
[2] F 
[3] V 

F00 
F00[1] F 

NAME CLASS: 2 SHAPE: 
5 
NEW NAME CLASS 



15 6 7 8 

4 5 6 7 8 

5 OWATCH 



^DEFINE FUNCTION TOO 
o SIMPLE ASSIGNMENT MODIFIES F 
nLINE 2 REFERENCES F 

^EXECUTE FOO 



2 SHAPE: 
9 

9 

F' 



^REPLACE PREVIOUS WATCHPOINT AND 



FOO 
F00[2] F 

Olfl JVMF CL4SS: 2 Sff/4P5: 
12 3 4 5 6 7 8 9 
12 3 4 5 6 7 8 9 

2 OWATCH 'F' 



vEHABLE DISPLAY IF REFERENCED 



^REPLACE PREVIOUS WATCHPOINT AND 



F *■ 5 

FOO 
113 WATCH POINT ACTIVATED 
F00[1] F +- i9 



rENABLE SIGNAL IF MODIFIED 
rNO SIGNAL FOR INTERACTIVE ASSIGNMENT 



[VARIABLE HAS BEEN MODIFIED) 

nSIMPLE ASSIGNMENT MODIFIES F 
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)SI 

room * 

UL 
F 

F 
12 3 4 5 6 7 8 9 

W 
5 

Possible Errors Generated 

Monadic Form 

9 RANK ERROR (NOT MATRIX DOMAIN) 

10 LENGTH ERROR 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 
Dyadic Form 

9 RANK ERROR (NOT MATRIX DOMAIN) 

9 RANK ERROR (NOT VECTOR DOMAIN) 

10 LENGTH ERROR 

15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 

15 DOMAIN ERROR (INCORRECT TYPE) 

15 DOMAIN ERROR (INVALID WATCH MODE) 

15 DOMAIN ERROR (NOT AN INTEGER) 

2 7 LIMIT ERROR (INTEGER TOO LARGE) 
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D XQ Executing Expressions 
Type 

Monadic System Function (sometimes quiet) 

Form 

result ■*- UXQ apl-expression 

Argument Domain 



Type 


Any 


Shape 


Any 


Depth 


Any 


Result Domain 




Type 


Any 


Rank 


Any 


Shape 


Any 


Depth 


Any 


Description 





D XQ executes the expression represented by its argument as if that expression 
were entered in immediate mode or included in a user-defined operation. For 
example, the expressions i 5 and UXQ ' i 5 ' return the same result: 



i5 
12 3 4 5 

DIS'i5' 
12 3 4 5 



The argument can be a numeric (any shape) or a character array (vector 
domain). If the argument to Q XQ is numeric, APL returns the value of the 
argument): 



UXQ 55 
55 
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APL treats a <CRxLF> in the argument as a statement separator as if it 
were input from the terminal, so multiple lines are allowed. The Q XQ function 
always returns a value: either the value of the last statement evaluated in its 
argument, or, if the last statement has no value, an empty array. For example: 

D+QXQ'5-m- 

3 + 2 
6' 
9 

5 



The D XQ function can execute system commands or invoke the function editor. 
For example: 

QXQ ' VR+FOO 
A+l 

B->-3 

R<-A+B 
V 



5 

FOO 
A B 



FOO 

QXQ')FNS' 
QXQ ' ) VARS ' 



QXQ^ERASE ', QXQ') VARS < nERASE ALL VARIABLES 

A 
11 VALUE ERROR 
A 

A 

Pendent D XQ functions are indicated by the ' □ XQ ' characters in the state 
indicator. For example: 

QXQ ')SI' 
QXQ 

Note that quiet functions are still quiet when executed, provided that □ XQ is 
the leftmost function in the statement: 

QXQ'Z^l' 
,QXQ'Z+1< 
1 
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When the argument is empty and numeric, the result is an empty numeric 
vector (UXQ i *-->■ i 0). For example: 

UXQ i0 

When the argument is empty and character, the result is an empty character 
vector ( ' ' = UXQ ' ' ) if a value is required by the expression. For example: 

QIC ' ' v QUIET, NO OUTPUT 

A+UXQ ' ' 

If APL encounters an error while evaluating the Q XQ function's argument, it 
does not signal an error; instead, it stops evaluating the argument and returns 
an empty array whose shape is n, where n is a number indicating the error 
that was encountered (see Appendix A for a complete description of all APL 
errors). The complete text of the error message is placed in Q ERROR. For 
example: 

3 + 2, 

4' 

10 

E 

(APL outputs a blank line) 

PE 
7 

UERROR 
1 UXQ SYNTAX ERROR (RIGHT ARGUMENT TO FUNCTION HISSING) 

3 + 2, 

A 

If you enter the attention signal while the UXQ function is executing, APL stops 
executing the argument to UXQ, and UXQ returns an empty array whose shape 
is 18. Then, the normal order of execution continues. 

The UXQ function cannot execute a branch statement; if one is entered, the 
branch is not taken, and the result of the Q XQ function, if needed, is an empty 
vector. Thus, UXQ never alters the flow of control within an operation. 

Possible Errors Generated 



9 RANK ERROR (NOT VECTOR DOMAIN) 
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VAX APL provides a wide variety of system commands that allow you to 
examine or change the state of the system. For example, you can do the 
following: 

• Clear, save, or name the active workspace 

• Load or copy a workspace from a secondary storage device 

• List workspace, variable, and user-defined operation names 

• Display the status of user-defined operations and local variables in the 
workspace 

• Set the index origin, the maximum number of significant digits, and the 
output line width 

• End an APL session 

Unlike system functions and system variables, system commands are not 
considered part of the APL language. 

System commands are particularly useful in function-definition mode, because 
they are executed immediately instead of being executed when the operation 
is executed. Thus, you can change the APL environment without exiting from 
the function editor. For example, if the terminal print width is set at 50, and 
you display an operation line that is 60 characters long, you could use the 
) WIDTH system command to change the print width so that the operation line 
is displayed on one line. 

Note that by giving system commands as arguments to the UXQ system 
function, you can use the commands within user-defined operations, rather 
than having them execute immediately. 
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3.1 System Command Form 

APL system commands begin with a right parenthesis, as shown in the 
following form: 

) white command-name [ space white arguments ] 

The right parenthesis is a required part of the system command name, white is 
optional white space; that is, zero or more spaces or tabs. Space is a required 
blank space. Arguments may or may not be allowed. See the individual 
descriptions of the system commands for more details. 

You can abbreviate a command name to its shortest unique form. Some system 
commands take required or optional parameters; when you include them, 
you must separate the individual items of the parameter list with at least 
one space or tab. If a system command that takes no arguments is followed 
by nonwhite space, or if an argument is invalid, APL signals INCORRECT 
PARAMETER. 

The following examples show the form of several system commands: 

) CONTINUE 

)C0NT 

) CONTIN 

)SAVE MY WORK 

)WSW ABC VAR6 N 

The first three examples invoke the same system command, ) CONTINUE; note 
that the first four letters of each of the command names are the same. In the 
fourth example, MYWORK is an argument to the ) SA VE system command. The 
fifth example shows a ) COPY command that takes a series of arguments. 

3.2 System Command Categories 

There are two broad categories of system commands: 

• Query commands obtain information 

• Action commands that change the state of a workspace or the operating 
environment 

The action commands can be further categorized into the following logical 
groups, which are described in the following sections: 

• Query/change commands find out about or change the state of the 
environment 

• APL action commands manipulate APL objects in a workspace 

• System action commands terminate or interrupt an APL session 
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• Workspace manipulation commands manipulate workspaces 

There are some system commands that specifically affect APL I/O; they are 
described in detail in the VAX APL User's Guide. Table 3-1 summarizes the 
system commands. 

3.2.1 Query System Commands 

The query system commands return information about the current state of the 
session, the active workspace, or the APL system or environment. The query 
system commands follow: 

)FNS 

)GRP 

)GRPS 

)NMS 

)OPS 

)VARS 

)SI 

)SINL 

)SIS 

) VERSION 

) CHARGE 

) OWNER 

)LIB 

)HELP 

3.2.2 Query/Change System Commands 

The query/change system commands are both action and query commands; 
that is, they can return information about the present state of the APL 
environment, or they can be used with an optional parameter to change the 
state of the environment. The ) ORIGIN command, for instance, can either 
return or change the index origin setting. 

In the following example, ) ORIGIN is used first as an action command; it 
sets the index origin to and reports that the previous setting was 1 . Then, 
) ORIGIN is used as a query command; it reports that the current setting of the 
index origin is : 

) ORIGIN 
WAS 1 

) ORIGIN 
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Each of the query/change commands can be thought of as displaying, or 
changing and displaying, a system variable. There are two types of system 
variables: workspace and session. 

Workspace variables are associated with a particular workspace; that is, they 
are saved and loaded with the workspace. The system commands associated 
with the workspace variables are as follows: 

)WSID IwsnameJ l/PASSWORDl: ftpwJU 
) PASSWORD H/ PASSWORD I : ftpwJM I pwj 
) ORIGIN InJ 
) DIGITS M 
) WIDTH M 

Session variables are associated with the current APL session; they do not 
change when the current workspace is changed, and they cannot be saved 
with a workspace. The system commands associated with the session variables 
follow: 

)MAXCORE M 
)MINCORE M 

Note that the system variables Q GAG, TLE, TT and Q VPC are also session 
variables. 

3.2.3 APL Action System Commands 

The APL action system commands cause some action to take effect within the 
current workspace. The APL action system commands are as follows: 

) CLEAR 

) EDIT object-name /qualifiers 

) ERASE l/FNSj l/GRPSj l/OPSj l/VARSj list 

) GROUP group-name \group-member-list\ 

)SIC 

)STEP Inll/ SILENT] 1/ INTO | /OVER] 

3.2.4 System Commands that Initiate System Action 

This section describes the system commands that terminate or interrupt an 
APL session or initiate some other program. 

You can exit from APL in a variety of ways: 

• Returning to the DCL command level 

• Terminating the APL session, optionally returning to the DCL command 
level 

• Terminating the session and saving the active workspace 
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• Interrupting the session and running other programs while at the DCL 
command level, eventually returning to APL 

The following system commands are in this category of commands that initiate 
system action: 

)MON 

)OFF 

) CONTINUE 

)PUSH 

) ATTACH 

)D0 

3.2.5 Workspace Manipulation System Commands 

The workspace manipulation system commands preserve, make active, and 
delete workspaces. They also copy objects from workspaces to the currently 
active workspace. The workspace manipulation system commands are as 
follows: 

)LOAD 

)XLOAD 

)SAVE 

)COPY 

)PCOPY 

)DROP 

3.3 System Command Reference 

The following sections describe the APL system commands in alphabetical 
order. Each description indicates the general category of the command: query, 
query/change, apl action, system action, or workspace manipulation. 

Table 3-1 lists all the system commands and gives a brief description of their 
uses. 

Table 3-1 System Commands 

Command Meaning 

) ATTACH Temporarily suspends the APL session and returns control to a 

specified process 

) CHARGE Displays a record of activity for the current APL session 

(continued on next page) 
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3.3 System Command Reference 



Table 3-1 (Cont.) System Commands 



Command 



Meaning 



) CLEAR Replaces active workspace with clear workspace 

) CONTINUE Saves active workspace and exits APL 

) COPY Copies global objects from another workspace 

) DIGITS Displays or changes the number of significant digits to be displayed 

) DO Executes a VMS command; returns output to APL 

) DROP Deletes workspaces or files from a directory-structured device 

) EDIT Edits a global object with the VAXTPU editor 

) ERASE Erases the named global object from the current workspace 

) FNS Displays an alphabetical list of global function names 

) GROUP Collects named objects into a group 

) GRP Lists members of a group 

) GRPS Displays an alphabetical list of group names 

)HELP Displays information about APL features 

) INPUT Diverts input to a device other than your terminal 

)LIB Displays names of workspaces or files on a directory-structured 
device 

)L0AD Retrieves a workspace from secondary storage 

)MAXC0RE Displays or changes the setting for maximum workspace size 

) MI TV CORE Displays or changes the setting for minimum workspace size 

) MON Returns you to operating system command level 

) NMS Displays all names in the symbol table 

) OFF Ends current APL session 

) OPS Displays an alphabetical list of global operator names 

) ORIGIN Displays or changes index origin 

) OUTPUT Diverts output from your terminal to another device 

) OWNER Displays information about the creation of the current workspace 

) PASSWORD Displays or changes the workspace password 

)PCOPY Same as ) COPY but protects names already in use 

(continued on next page) 
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3.3 System Command Reference 



Table 3-1 (Cont.) System Commands 



Command 



Meaning 



) PUSH Temporarily suspends the APL session, returning control to the 

operating system 

) SA VE Saves a copy of the active workspace 

) SI Displays workspace state indicator 

)SIC Clears workspace state indicator 

) SINL Displays workspace state indicator, local symbols for each user- 

defined operation, and argument to pending execute functions 

) SIS Displays workspace state indicator, currently executing line, and 

argument to pending execute functions 

)STEP Executes lines of a function one at a time 

) VARS Displays an alphabetical list of global variables 

) VERSION Displays the APL version numbers for the workspace and interpreter 

) WIDTH Displays or changes the terminal line width 

) WSID Displays or changes workspace name; optionally changes workspace 

password 

) XL OAD Retrieves a workspace from secondary storage without executing 

ULX 
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) ATTACH Interacting with Other Processes 
Type 

Action System Command 

Form 

) ATTACH {process-name} 

Qualifiers 

/PARENT 

Specifies that you want to attach to the first process established in the current 

job. 



Description 



Note that you must specify either /PARENT or the process-name, but you cannot 
specify both. 

) ATTACH interrupts the APL session and attaches to a process that already 
exists within your current job. The APL session is not terminated when you 
use ) ATTACH. To return to APL, you can use the DCL command ATTACH on 
the process name of the APL process. When you return to the interrupted 
APL session, program execution resumes at the point after the execution of the 
) ATTACH command. 

Examples: 

QGAG +■ 2 ^BROADCASTS HILL BE DISPLAYED IN APL CHARACTERS 

^EXECUTE MAIL IN A SUBPROCESS NAMED MAILPROC 
)PUSH/PROCESSNAME=MAILPROC MAIL 

MAIL> ATTACH / 'PARENT 

nWE ARE BACK IN APL 
dGO READ THE NEW MAIL 
) ATTACH MAILPROC 
You have 1 new message. 

MAIL>read/new 

#1 8-NOV-1999 15:15:15:41 
From: APLVAX: :USER2 
To: USER1 
CC: 
Subj : Pizza today? 

Do you want to have pizza for lunch today? 
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MAIL> attach/parent 

aWE ARE BACK IN APL 
)D0 SHOW PROCESS/ SUBPROCESSES 

8-JVO7-1990 15:39:0i+. 42 User: USERl Process ID: 00000067 

Node: APLVAX Process name: f*USER<-2fi 

There are 2 processes in this job: 

+-TWA2: 

USER1+2 {*) 

nUSERl+i IS THE PROCESS FOR DO) 
)0FF 
TUA2: THURSDAY 8-NOV-19S0 15:39:05.01 
CONNECTED 00:00:39.53 CPU TIME 00:00:01.09 
6 STATEMENTS 1 OPERATIONS 

306 PAGE FAULTS 110 BUFFERED 10 125 DIRECT 10 
$ show process/subprocesses 

8-NOV-1990 15:47:58.25 User: USERl Process ID: 00000005A 

Node: APLVAX Process name: "_TWA4:" 

There are 3 processes in this job: 

_TWA4: (*) 
USER1_1 
MAILPROC 

Possible Errors Generated 

22 INCORRECT PARAMETER (MISSING ARGUMENT) 

22 INCORRECT PARAMETER (UNRECOGNIZED QUALIFIER KEYWORD) 

lli+ ERROR PROCESSING ATTACH (ATTACH REQUEST REFUSED) 

111+ ERROR PROCESSING ATTACH (INVALID LOGICAL NAME) 

114- ERROR PROCESSING ATTACH (NONEXISTENT PROCESS) 

24-9 EXTRANEOUS CHARACTERS AFTER COMMAND 

38 3 PARENT QUALIFIER REPEATED 
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) CHARGE Displaying Accounting Information 
Type 

Query System Command 

Form 

) CHARGE 



Description 

) CHARGE displays a record of activity during the current APL session and 
includes the following: 

Your terminal identification 

Current time and date 

Length of time connected to APL 

Amount of computer CPU time used inside APL 

Number of APL operations executed 

Number of page faults while inside APL 

Number of buffered I/O and number of direct I/O while inside APL 

For example: 

) CHARGE 
SYS$INPUT: WEDNESDAY 14-JVOF-1990 16:03:22.16 
CONNECTED 00:00:01.33 CPU TIME 00:00:00.40 
STATEMENTS OPERATIONS 
16 PAGE FAULTS 20 BUFFERED 10 15 DIRECT 10 

Possible Errors Generated 



2 2 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 
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) CLEAR Clearing the Active Workspace 
Type 



Form 



APL Action System Command 



) CLEAR 



Description 



) CLEAR empties the active workspace by erasing all variables, groups, and 
user-defined operations; resetting all workspace variables (but not session 
variables) to their default values; closing all open files; and clearing the state 
indicator. 

The clear workspace has the following characteristics: 

Contains no user-defined operations, groups, or variables 

Has an index origin (Q 10) of 1 

Has an output line length (Q PW) determined by the operating system width 
specification 

Has a comparison tolerance value (Q CT) of iff" 15 

Has a random link value {URL) of 695197565 

Has an empty character array as the value for ULX, UTRAP, Q ERROR, UL, 
and UR 

Has the automatic save feature turned off (D A US is 0) 

Outputs the negative sign (" ) in TTY mode as .NG (□ NG is 1) 

Displays both primary and secondary error messages when an error occurs 

(□ TERSE is 0) 

Has a workspace and interpreter version that are the same (the lines 
returned by D VERSION match) 

Displays numbers with ten significant digits (□ PP) 

Has a clear symbol table and state indicator 

Has the name CLEAR WS 

Has an empty password 
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• Requests quad input with the message Q : followed by a <CRxLF> and six 
blanks (DSF) 

• Has a default DDC value of ("l 10 2) ' ' , which means that there are no 
boxes around enclosed arrays 

Note that APL gives you a clear workspace when you begin a work session, 
unless you have a CONTINUE workspace in your default device and directory 
area, or unless you use an initialization stream to specify a workspace to be 
loaded. Also note that ) CLEAR clears only the active workspace; it has no effect 
on workspaces you have saved with the ) SA VE system command. 

When the ) CLEAR command completes execution, APL displays the message 
CLEAR WS. For example: 

) CLEAR 
CLEAR WS 

)MINC, )MAXC, UGAG, TLE, and UTT are not affected by ) CLEAR. 

Possible Errors Generated 



22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 



3-12 APL Reference Manual 



System Commands 

) CONTINUE Saving the Workspace and Ending the Session 



) CONTINUE Saving the Workspace and Ending the Session 
Type 

System Action System Command 

Form 

) CONTINUE iHOLD \ LOGOUTj 

Default in Clear Workspace 

HOLD 

Description 

) CONTINUE works the same way as the ) OFF system command, except that 
before ending the session ) CONTINUE saves the active workspace in your 
default device and directory area under the name CONTINUE .API. If files 
named CONTINUE. APL already exist in your directory, the new CONTINUE 
workspace will have a version number that is one greater than the next most 
recent version. 

The HOLD parameter (the default) returns you to DCL command level after 
ending the APL session. The LOGOUT parameter logs you off the system after 
ending the APL session. The ) CONTINUE command prints the same message 
that the )SAVE command prints, followed by the same summary information 
that ) OFF displays. For example: 

) CONTINUE HOLD 
WEDNESDAY 28-AT07-1990 16:04:29.46 15 BLKS 
SYS$INPUT: WEDNESDAY 28-JV07-1990 16:04:29.90 
CONNECTED 00:00:01.62 CPU TIME 00:00:00.42 
STATEMENTS OPERATIONS 
191 PAGE FAULTS 24 BUFFERED 10 21 DIRECT 10 

If a CONTINUE workspace exists in your default area when you begin an APL 
session, it is loaded as your active workspace, unless you specify a different 
workspace in an APL initialization stream, or unless the workspace had a 
password when it was saved. If the CONTINUE workspace is saved with a 
password, APL signals WORKSPACE LOCKED when the APL session begins. 
You can still load the workspace by executing the command )LOAD CONTINUE 
/ P AS SWORD :pw. 
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Note that the name of a CONTINUE workspace that is loaded is not CONTINUE; 
the name is the one the workspace had when it was saved. The load message 
displayed when APL is invoked identifies what the name was when the 
workspace was saved. For example: 

)L0AD CONTINUE 
SAVED WEDNESDAY 28-JV07-1990 16:04:29.46 15 BLKS MS EXAMPLE 

)WSID 
EXAMPLE 

Note 



APL does not delete your CONTINUE workspace after it is loaded. A 
particular CONTINUE workspace in your default area may be loaded as 
your active workspace each time you invoke APL, not just the first time 
that you invoke APL after the workspace was created. If you do not 
want the CONTINUE workspace to be loaded, you must explicitly delete 
it from your default area, or specify a different workspace in an APL 
initialization stream. 



Possible Errors Generated 

15 DOMAIN ERROR{EXTRANEOUS CHARACTERS AFTER COMMAND) 

22 INCORRECT PARAMETER (UNRECOGNIZED QUALIFIER KEYWORD) 



3-14 APL Reference Manual 



System Commands 

COPY Copying Objects from a Workspace 



) COPY Copying Objects from a Workspace 
Type 



Manipulation System Command 

Form 

) COPY wsname llistl 

Qualifiers 



/PASSWORDlllpwffl 

Specifies the password associated with the stored workspace. 

/CHECK 

Causes APL to examine the workspace for possible corruption (damage to 
the internal structure of the workspace). If damage is detected, a message 
is displayed and APL tries to recover as much information as possible from 
the workspace and continue the copy. The recovered workspace may be 
missing APL variables, user-defined operations, individual lines of user- 
defined operations, and other APL objects that were damaged. The user must 
determine what named objects have been removed from the workspace. 



Description 



) COPY retrieves global user-defined operations, global variables, and groups 
from a stored workspace (wsname) and places them into your active workspace. 
If there is a password associated with the stored workspace, you must include 
it in the command string. 

You can copy all the named objects in a workspace or a subset of them; list 
identifies the specific objects to be copied. When you specify a list of objects, 
you can use the * and * wildcards. If you omit the list parameter, all user- 
defined operations, variables, and groups are copied. )COPY does not transfer 
local values for variables and functions, nor does it copy the state indicator, 
channel assignments, or any system variable such as the print width, index 
origin, or print precision. 

If your active workspace contains objects with the same name as those in the 
copied workspace, ) COPY replaces the global (but not the local) values in your 
active workspace with the copied ones. For example, if B is a variable in the 
active workspace with a global value of 10 and a local value of 5, and the 
workspace being copied has a variable B with a global value of 20, after ) COPY 
is executed the active workspace will have a variable B with a global value of 
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20 and a local value of 5. A suspended or pendent operation, or an operation 
still being defined in the active workspace is not replaced, and an operation 
being created in the workspace being copied is not copied. 

When you copy a group, all members of the group are copied along with their 
values. However, if a member of a group is itself a group, APL copies only the 
group name and not the value. Thus, for example, suppose the group GROUPl 
has as members the variables A and B , and the group GROUPl. Also suppose 
that GR0UP2 has as members the variables C and D. Then, if you copy GROUPl, 
you copy the values of A and B , but only the name of GROUP2, not the values of 
C and D . 

The ) COPY command displays the same message as the )LOAD command. Note 
that the size printed in this message is the size (in disk pages) of the active 
workspace after execution of the ) COPY command completes. If the list to be 
copied contains an object that is not in the specified workspace, APL returns 
the message NOT FOUND:, followed by a list of the objects (separated by tabs) 
that were not found. The objects that were found are still copied, however. 

The )C0PY command performs the same operation as the QCO system function 
(see Chapter 2), but Q QCO does not display messages to confirm that the copy 
was successful. 

Examples: 

)C0PI AVER 
SAVED WEDNESDAY 28-TOF-1990 16:20:42.14 24 BLKS 

)C0PY AVER B 
SAVED WEDNESDAY 2S-NOV-1990 16:20:12.14 24 BLKS 

)C0PY AVER G 
SAVED WEDNESDAY 28-JVOK-1990 16:20:42.14 24 BLKS 
NOT FOUND: G 

Possible Errors Generated 



2 2 INCORRECT PARAMETER 

2 2 INCORRECT PARAMETER^ ILL FORMED NAME) 

27 LIMIT ERROR(ARGUMENT STRING IS TOO LONG) 

8 3 DAMAGED WORKSPACE HAS BEEN CORRECTED (SOME SYMBOLS MAY HAVE 
BEEN ERASED) 



3-16 APL Reference Manual 



System Commands 

) DIGITS Output Precision 



) DIGITS Output Precision 
Type 

Query/Change System Command 

Form 

) DIGITS M 

Default in Clear Workspace 

10 

Description 

) DIGITS displays or changes the value of the print precision system variable 

(DPP). 

The print precision (n in the form) is the number of significant digits displayed 
in APL floating-point output; it can be an integer from 1 to 16. It does not 
affect the precision of internal calculations or the display of integers. APL 
rounds off any number that has more digits than the current setting. 

Executing the ) DIGITS command in change mode has the same effect as 
assigning a value to the Q PP system variable (see Chapter 2). 

Examples: 

) DIGITS 
10 

1.234-56789123456789 
1.231567891 

)DIG 5 
WAS 10 

1.23456789123456789 
1.2346 

)DIG 2 
WAS 5 

1.23456789123456789 
1.2 
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Possible Errors Generated 

2 2 INCORRECT PARAMETER {EXTRANEOUS CHARACTERS AFTER COMMAND) 
2 2 INCORRECT PARAMETER {ILL FORMED NUMERIC CONSTANT) 
2 2 INCORRECT PARAMETER {PARAMETER OUT OF RANGE) 
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) DO Executing a DCL Command 
Type 

System Action System Command 

Form 

)D0 command-string 

Qualifiers 

/LOWERCASE 

Refers to how you want ) DO to translate any output from the execution of the 
command string. Without this qualifier, the )D0 command converts any ASCII 
lowercase letters to uppercase unless you are using VT102, VT220, VT240, 
VT320, VT330, VT340, DECterm, VS, or TTY mnemonic mode, or unless the 
output is the argument to execute (either UXQ or ± ). Use the /LOWERCASE 
qualifier if you do not want this conversion to occur. 

/NOKEYPAD 

Specifies that you do not want the keypad characteristics of the current process 
to be available to the new subprocess. The default is that the characteristics 
are available. 

/NOLOGICALS 

Specifies that you do not want the logical name table from the current process 

to be available to the new subprocess. The default is that the table is available. 



/NOSYMBOLS 

Specifies that you do not want the global and local symbol table (defined at the 
DCL level) from the current process to be available to the new subprocess. The 
default is that the symbol table is available. 



Description 



) DO interrupts the APL session and creates a VMS subprocess, putting you 
at the DCL command level without terminating the APL session. Unlike 
the )PUSH command, )D0 attempts to recover any output resulting from the 
execution of the command string. 
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With ) DO, you must always include a command string (do not enclose the 
string in quotation marks); VMS creates a subprocess, executes the command 
specified, and then returns to APL when the execution completes. For example, 
the following executes the DCL command SHOW TIME and returns its output 
to APL: 

DOTIME+QXQ' )D0 SHOW TIME' 
DO TIME 
8-^07-1990 16:25:21 

The command string must be no longer than 132 characters (after translation 
to ASCII), not including leading white space (spaces or tabs before the 
argument begins), but including all other white space within the argument. 

Any output written to SYS$OUTPUT or SYS$ERROR is retrieved by APL. See 
the VMS DCL Dictionary for a description of SYS$OUTPUT and SYS$ERROR. 

While you are at DCL command level, your terminal is in ASCII rather than 
APL mode, and your terminal characteristics (such as output line width) revert 
to the system settings. When you return to APL, the APL character set is 
restored, and your Q PW setting is the same as it was before you executed the 
) DO command (although the default for D PW changes if you changed your 
system terminal width). However, other terminal characteristics you may have 
changed at command level (for example, the OGAG setting, or the ability to 
input lowercase characters) remain changed. 

Possible Errors Generated 



2 2 INCORRECT PARAMETER {LOWERCASE QUALIFIER REPEATED) 

2 2 INCORRECT PARAMETER {MISSING ARGUMENT) 

2 2 INCORRECT PARAMETER {NOLOGICALS QUALIFIER REPEATED) 

2 2 INCORRECT PARAMETER {NOSYMBOLS QUALIFIER REPEATED) 

22 INCORRECT PARAMETER {NOKEYPAD QUALIFIER REPEATED) 

7 3 SUBPROCESS ERROR {COMMAND BUFFER OVERFLOW 
SHORTEN EXPRESSION OR COMMAND LINE) 
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)DROP Deleting Stored Workspaces or Files 
Type 

Workspace Manipulation System Command 

Form 

) DROP file-spec 

Description 

)DROP can delete any file for which you have the necessary protection 
privileges. You can delete one, several, or all the files on a device and directory. 

If you do not include a device and directory, your default device and directory 
are assumed; however, you must always include a file name, file type, and 
version number. You may use a wildcard designator to substitute for the 
version number or for all or part of the file name or file type. In the following 
example, all files on the default device and directory that begin with the letter 
S are deleted. APL prints the file specification for each file dropped. For 
example: 

)DR0P *.LIS;* 
iDELETE-I-FILDEL, DEV1:LAPLGRP]D0C.LIS;1 deleted (3 blocks) 
^DELETE-I-FILDEL, DEV1:IAPLGRP]SAMPLE.LIS;2 deleted (3 blocks) 
tDELETE-I-FILDEL, DEVI: IAPLGRP] SAMPLE. LIS ;1 deleted (3 blocks) 
tDELETE-I-TOTAL, 3 files deleted (9 blocks) 

The maximum length of the ) DROP command argument is 121 characters 
(after translation to ASCII), not including leading white space (spaces and tabs 
before the argument begins), but including all other white space within the 
argument. 

Executing the )DROP command is equivalent to executing the DCL command 
DELETE/LOG. For more details about the DELETE command, see the VMS 
DCL Dictionary. 

Possible Errors Generated 



22 INCORRECT PARAMETER {LINE TOO LONG TO TRANSLATE) 
2 2 INCORRECT PARAMETER (MISSING ARGUMENT) 
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) EDIT Editing with VAXTPU 
Type 



APL Action System Command 



Form 



) EDIT objectname 

Qualifiers 

In o\i command 

Allows you to specify an initialization file to VAXTPU. The value for filespec 
is a VMS file specification. If you omit the /COMMAND qualifier, or if you do 
not specify a filespec value, VAXTPU uses the file specification assigned to the 
logical name TPUINI as a default. 

iNO^/ DISPLAY 

Tells VAXTPU that you are using a support ANSI CRT terminal. This is the 

default. You should specify /DISPLAY only during an interactive session. 

/NODISPLAY tells VAXTPU that your are not using a supported terminal. 

You should use this qualifier only when you run VAXTPU procedures in batch 

mode. 

/ EXECUTEg:tpucommand$ 

Allows you to specify a VAXTPU command string that you want to execute 
after the editor finishes any command or section files. Note, however, that 
VAXTPU does not execute the /EXECUTE qualifier when either the command or 
section file contatins a QUIT or EXIT command. 

The value for tpucommand is a character string containing one or more 
VAXTPU statements that you want VAXTPU to execute. It should not contain 
any non-ASCII APL characters or embedded <CRxLF>s. You do not have to 
place quotation marks around the string, but if quotation marks are necessary 
for the VAXTPU operation, they must be balanced. The maximum length of 
the string is 100 characters, and it must be terminated by the end of the line 
or by another qualifier. If you do not specify tpucommand, APL ignores the 
/EXECUTE qualifier. 

The /EXECUTE qualifier is particularly useful when you run APL and )EDIT 
in batch mode. For example, you can set up an error-checking routine to 
handle situations where the VAXTPU file is too large to return to the APL 
environment. If you create a VAXTPU procedure called CHECKMESBUFFER 
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that checks the VAXTPU message buffer for a WORKSPACE FULL error, you can 
call the procedure with the /EXECUTE qualifier: 

)EDIT F00/ EXECUTE -.CHECKMESBUFFER 

When you first invoke VAXTPU, the section and command files run, and the 
/EXECUTE qualifier calls the CHECKMESBUFFER procedure. The procedure 
does nothing because there is currently no WORKSPACE FULL error message 
in the VAXTPU message buffer. However, if the editing session ends and the 
file is too large, APL reinvokes VAXTPU. This time the CHECKMESBUFFER 
procedure detects the error message and handles it accordingly. 

ILC 

Determines whether the line numbers of a user-defined operation appear in 
the VAXTPU editor. This qualifier is useful because it allows you to view the 
current line numbers associated with the lines of the operation. APL ignores 
the ILC qualifier for objects that are not operations. 

Once the file is in the editor, the line numbers no longer determine the 
organization of the lines in the operation. When the file returns to the APL 
environment, APL assigns new line numbers based on the order that it reads 
the records from the VAXTPU editor. If you add new lines to the operation, 
you do not have to include any line numbers. 

When you do not specify ILC, APL generates the canonical representation of 
the operation in the VAXTPU editor. (The canonical representation does not 
include line numbers.) 

/modeI .-model 

Allows you to determine the input/output mode for the data moving between 
the AP and VAXTPU environments. The value for mode is the integer 2 or 3, 
and represents Q and i , respectively. If you omit the /MODE qualifier, or if you 
do not specify a mode value, APL uses /MODE : 2 as a default. 

Note that you must specify MODE : 3 if you have embedded line feeds in an 
object and want them to remain intact in the file that VAXTPU returns to 
APL. However, be aware that turns off APL overstrike and TTY mnemonic 
translation. 

INClmcJ 

Determines the name class of the object you are editing. This qualifier is 
useful only when you intend to create a new object in the editor. The value for 
nc is an integer that specifies the name class of the new object, which has the 
following characteristics: 
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Name Class Data Type Shape 



2 Character Vector 

3 Function Not applicable 

4 Operator Not applicable 



When you omit the /NC qualifier, or when you specify /NC without a value, 
APL uses the name class of the object named by objectname as the default. If 
objectname specifies a currently undefined object, APL uses 2 as the default 
value. 

/NGl:ng% 

Determines how VAXTPU displays the APL high minus sign (" ), which is used 
to indicate a negative number. This qualifier only affects the representation of 
numeric variables; numeric values within operations are not affected. 

/NG is the equivalent of DNG and accepts the same values (0, 1, or 2). When ng 
is 1, negative numbers are preceded by the high minus sign (~ ). When ng is 0, 
negative numbers are preceded by the minus sign (- ). When ng is 2, negative 
numbers are preceded by the APL plus sign (+ ). (The setting 2 is used when 
reading or writing ASCII files; the ASCII minus sign translates to the APL 
plus sign. See the discussion of DNG in the VAX APL Reference Manual for 
more information.) 

The default setting for /NG is the current setting for DNG. 

/PPl:ppJ 

Determines the print precision of noninteger numeric values sent to VAXTPU. 

/PP is the equivalent of DPP and accepts the same values (1 to 16). If you omit 

the / PP qualifier, APL uses the current value of D PP as the default. If you 

specify /PP but do not include a value, APL uses the maximum allowable value 

(16). 

/jw|[.-piv]| 

Determines how APL segments an object for output to the temporary file in the 
VAXTPU editor. The value for pw specifies the maximum number of characters 
in a single line of output. /PW is the equivalent of QPW and accepts the same 
values (35 to 2044). However, the greatest value that VAXTPU will accept from 
APL is 900. If you specify a /PW value greater than 900, APL selects 900 by 
default. If you do not specify /PW, or if you specify /PW without a value, then 
the default setting is D PW or 900, whichever is smaller. 
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VAXTPU truncates any record that has a length greater than 900. To avoid 
losing data, APL forms records in the following manner when creating the 
temporary file: 

Functions APL breaks records between each line 

Matrices APL breaks records between each row 

Vectors APL breaks records at each <CR> <LF> 

When you enter VAXTPU, some line wrapping may occur, depending on the 
setting used for / PW. This could cause unexpected changes in the edited object, 
and may result in an error when you attempt to end the editing session. To 
avoid confusion, APL places a warning message in the VAXTPU message buffer 
as you enter the editing session: LINE WRAP HAS OCCURED. The semantics 
for line wrapping are as follows: 

• If /PW is not specified, APL wraps records with length > 90 

• If / PW is specified, APL wraps records with length > 9 o L D PW 

• If /PW=pw is specified, APL wraps records with length > 900 L pw 

iNOj/SECTiONfrfilespecJ 

Allows you to specify a section file to VAXTPU. The value for filespec is a 
VMS file specification. If you omit the /SECTION qualifier, or if you do not 
specify a filespec, VAXTPU uses the file specification assigned to the logical 
name TPUSECINI as a default. If you desire to use the EDT emulation mode, 
specify / SECTION -.EDTSECIN I. 

I TERMlNALfctermtype] 

Determines the terminal type you want to use during the )EDIT session. The 

values for termtype, and the character sets that they represent are as follows: 

Terminal Type Character Set 



TTY 


TTY 


KEY 


KEY 


BIT 


BIT 


COMPOSITE 


COMPOSITE 


VT102 


BIT 


VT220 


COMPOSITE 


VT21Q 


COMPOSITE 


VT320 


COMPOSITE 
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Terminal Type Character Set 



VT330 


COMPOSITE 


VT3H0 


COMPOSITE 


HDS201 


COMPOSITE 


HDS221 


COMPOSITE 


vs 


COMPOSITE 


DECTERM 


COMPOSITE 



If you omit the /TERMINAL qualifier, or if you do not specify the termtype value, 
APL uses the current terminal type as the default. 

Description 

The ) EDIT system command allows you to edit global APL objects with the 
VAXTPU editor. You can edit user-defined operations and variables. You 
cannot edit enclosed arrays, and you cannot modify an operation that is 
suspended or pendent. (If you edit a suspended or pendent operation, APL 
puts an appropriate message in the VAXTPU message buffer, and you must 
end the VAXTPU session with a QUIT command.) 

When you invoke ) EDIT, APL creates a temporary file containing the object 
you want to edit and then invokes VAXTPU. When you exit VAXTPU, APL 
reads the edited file from VAXTPU into the workspace. Note that APL returns 
you to the VAXTPU editor if an error occurs as the file reenters the workspace. 

For more information about VAXTPU, see the VAX Text Processing Utility 
Manual. 

Note that ) EDIT is also described in the VAX APL User's Guide. 

Possible Errors Generated 



5 DEFN ERROR (OPERATION SUSPENDED OR PENDENT) 

15 DOMAIN ERROR (ERROR ACTIVATING IMAGE) 

111 EDIT COMMAND ERROR (xx QUALIFIER REPEATED) 

111 EDIT COMMAND ERROR (ARGUMENT TO xx IS OUT OF RANGE) 

111 EDIT COMMAND ERROR (BAD ARGUMENT TO XX) 
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111 EDIT COMMAND ERROR (EDIT COMMAND UNAVAILABLE DURING FUNCTION 
DEFINITION) 

111 EDIT COMMAND ERROR {ENCLOSED ARRAY NOT ALLOWED) 

111 EDIT COMMAND ERROR (EXECUTE QUALIFIER ARGUMENT IS TOO LONG) 

111 EDIT COMMAND ERROR (ILL FORMED NUMERIC CONSTANT) 

111 EDIT COMMAND ERROR (ILL FORMED NUMERIC MATRIX) 

111 EDIT COMMAND ERROR (ILLEGAL NAME CLASS) 

111 EDIT COMMAND ERROR (INCORRECT PARAMETER) 

111 EDIT COMMAND ERROR (MISSING ARGUMENT) 

111 EDIT COMMAND ERROR (OPERATION LOCKED) 

111 EDIT COMMAND ERROR ( UNRECOGNIZED QUALIFIER KEYWORD) 

111 EDIT COMMAND ERROR ( VOLUME TOO LARGE) 



APL Reference Manual 3-27 



System Commands 

) ERASE Erasing Global Names 



) ERASE Erasing Global Names 
Type 

APL Action System Command 

Form 

) ERASE list 

Qualifiers 

/FNS 

Limits the name class of the objects to functions. 

/VARS 

Limits the name class of the objects to variables. 

/GRPS 

Limits the name class of the objects to groups. 

/OPS 

Limits the name class of the objects to operations. 



Description 



) ERASE deletes the APL objects named in the list; it undefines global user- 
defined functions and operations, erases global variables, and disperses groups 
and erases their members. 

When you specify list, you can use the * and * wildcards. You can use the 
/FNS, /GRPS, /OPS, and /VARS qualifiers in conjunction with wildcards to limit 
the name class of the objects being erased. 

You cannot erase pendent or suspended operations, nor can you erase labels or 
other local names. If you are inside the A editor, you cannot erase the function 
being edited. 

If a member of the named group is itself a group, the group name is erased, 
but the members of the subgroup remain intact. For example: 
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) CLEAR 
CLEAR WS 

)L0AD TRIG_CIRCLE 
SAVED THURSDAY 8-NOV-1990 15:08:07.52 12 BLKS 

)FNS 
ARC COS DIAM RADIUS SIN TAN 

aTRIG CONTAINS THE GROUP CIRCLE 

)GRP TRIG 
SIN COS TAN CIRCLE 

aSHOW MEMBERS OF GROUP CIRCLE 

)GRP CIRCLE 
ARC RADIUS DIAM 

) ERASE TRIG 

)GRP TRIG 
22 INCORRECT PARAMETER (NOT A GROUP) 

)GRP TRIG 

A 

^ERASING TRIG ERASED GROUPNAME CIRCLE 
)GRP CIRCLE 
22 INCORRECT PARAMETER (NOT A GROUP) 
)GRP CIRCLE 

A 

a MEMBERS OF CIRCLE NOT ERASED 
)FNS 
ARC DIAM RADIUS 

If a specified object cannot be erased, either because such an operation is 
illegal or because the object is undefined, the following message is displayed: 

NOT ERASED: list of objects 

The objects are separated by tabs. There is no message when ) ERASE is 
successful. 

Note that ) ERASE leaves a slot in the symbol table for the erased name 
(symbol). Although you erase a symbol, the slot in the symbol table still exists. 
If you reuse a name that was in the symbol table, APL places it in the same 
slot where it was before. If you do a ) COPY of the workspace into a CLEAR WS, 
APL rebuilds the workspace, thus erasing the slot as well as the symbol. 
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Examples: 

D<-B-<-2 3 H 
2 3 4 

) ERASE B 
E 
11 VALUE ERROR 



V R+F 
[1] 

[2] )ERASE F 
NOT ERASED: F 
[2] V 

)FNS G* 
Gl GI 

)VARS G* 
G3 Gl 

) ERASE /FNS G* 

)FNS 

)VARS 
GZ G4- 

Possible Errors Generated 



f)F CANNOT BE ERASED 



aUSE QUALIFIER TO LIMIT WILDCARD 
^FUNCTIONS £71 AND G2 ARE GONE 
^VARIABLES GZ AND (74 STILL DEFINED 



2 2 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) 

2 2 INCORRECT PARAMETER {ILL FORMED NAME) 

2 7 LIMIT ERROR (ARGUMENT STRING IS TOO LONG) 
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) FNS Displaying a List of Functions 
Type 

Query System Command 

Form 

) FNS Ustart-string^stop-stringJJ 

Qualifiers 

/ wsid •. wsnameu: I password -. pwj 

Allows you to specify a nonactive workspace. If the nonactive workspace was 

saved with a password, you must also specify the /PASSWORD qualifier. 



Description 



) FNS displays a list of the global names used as user-defined function names 
in a workspace. By default, APL displays the list from the currently active 
workspace. 

The optional string parameters identify starting and stopping points for 
the list. When you specify the string parameters, you can use the * and + 
wildcards. The objects are listed in OAV order, separated by tabs. Each output 
line in the list begins in column one. 

Note that the wildcard determines the start-string. There is no wildcard for 
the stop-string. 

If you use ) FNS with no parameters, APL displays all the global function 
names in the workspace: 

)L0AD FNS 
SAVED THURSDAY 8-H0V-1990 17:12:11.52 41 BLKS 

)FNS 
ALPH MLB INVRS INVT LSQ 

If you include just one argument, APL uses Z as the default for the stop-string: 

)L0AD OPERS 
SAVED THURSDAY 8-N0V-1990 18:06:12.76 12 BLKS 

)FNS Iff 
IHVRS INVT LSQ 

)FNS LNV INV 
IHVRS INVT 
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To obtain a list of all user-defined function names that begin with a given 
prefix, use the prefix for both arguments or use a wildcard: 

)L0AD OPERS 
SAVED THURSDAY 8-JV07-1990 18:06:12.76 12 BLKS 

)FNS INV* 
INVRS INVT 

Possible Errors Generated 



1 FILE NOT FOUND (FILE NOT FOUND) 

2 2 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 
22 INCORRECT PARAMETER (FILE SPECIFICATION IS MISSING) 

22 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) 
2 2 INCORRECT PARAMETER (NOT A LETTER) 
5 7 FILE DOES NOT CONTAIN A WORKSPACE 
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) GRO UP Defining or Dispersing a Group 
Type 

APL Action System Command 

Form 

) GROUP group-name ^group-member-list^ 

Description 

) GROUP collects APL objects together under a single name. The objects can be 
variables, user-defined operations, and other group names. When you specify 
the objects, you can use the * and t- wildcards. 

The ) GROUP command is often used with the )COPY and )PCOPY commands. 
After collecting a set of operations and variables under one group name, you 
can specify the name in a ) COPY or ) PCOPY command to copy the entire 
collection at one time. 

In the following example, the functions and variables named INT, FUTVAL, and 
PRESVAL are collected into a group named FINANCIAL: 

)GR0UP FINANCIAL INT FUTVAL PRESVAL 

To add a new member to an existing group, you must list the group name as an 
item in the member list. Thus, the variable TAX is added to the group named 
FINANCIAL as follows: 

) GROUP FINANCIAL TAX FINANCIAL 

To disperse a group, specify the group name without a group member list. The 
group name will no longer be defined, but the individual members of the group 
will still exist under their original names. The following command disperses 
the group FINANCIAL: 

) GROUP FINANCIAL 
A group name is always global; you cannot localize it. For example: 
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A+l 

flf-2 

VF;C 
[1] R+-UXQ 'GROUP CAB' 
[2] V 

F 

)GRPS 



Here, the ) GROUP command executed inside the function F created a global 
group name C , even though C was included in the function's local symbol list. 

Possible Errors Generated 



2 2 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 

2 2 INCORRECT PARAMETER (ILL FORMED NAME) 

2 2 INCORRECT PARAMETER (MISSING ARGUMENT) 

2 4 NOT GROUPED, NAME IN USE 
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) GRP Displaying the Members of a Group 
Type 

Query System Command 

Form 

) GRP group-name 

Qualifiers 

/wsid: wsname n / password -. piyfl 

Specifies a nonactive workspace. If the nonactive workspace is saved with a 

password, you must also specify the /PASSWORD qualifier. 



Description 

) GRP displays the names of the objects associated with the group name. The 
names are listed in the order in which they are entered into the group and are 
separated by tabs. 

For example: 

)GR0UP APLGRP LEE PETER STAN DAVE ERIC CHIP CHRIS SHOT A 
)GRP APLGRP 
LEE PETER ST AH DAVE ERIC CHIP CHRIS SHOT A 

Possible Errors Generated 

1 FILE NOT FOUND (FILE NOT FOUND) 

2 2 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 
2 2 INCORRECT PARAMETER (ILL FORMED NAME) 

22 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) 

22 INCORRECT PARAMETER (MISSING ARGUMENT) 

2 2 INCORRECT PARAMETER (NOT A GROUP) 

5 7 FILE DOES NOT CONTAIN A WORKSPACE 
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) GRPS Displaying a List of Groups 
Type 

Query System Command 

Form 

) GRPS Istart-stringfstop-stringJJ 

Qualifiers 

/wsid -. wsnameii/ password ■. piyfl 

Specifies a nonactive workspace. If the nonactive workspace was saved with a 

password, you must also specify the /PASSWORD qualifier. 



Description 



) GRPS displays a list of group names in a workspace. By default, APL displays 
the list from the currently active workspace. 

When you specify the string parameters, you can use the * and * wildcards. 
The names are listed in D A V order, separated by tabs. Each output line in the 
list begins in column 1. 

Note that the wildcard determines the start-string. There is no wildcard for 
the stop-string. 

If you use ) GRPS with no parameters, APL displays all the group names in the 
workspace. For example: 

)GRPS 
ALPH HILB INVRS INVT LSQ 

If you include just one argument, APL uses Z as the default for the second 
string: 

)GRPS IN 
INVRS INVT LSQ 

)GRPS INV INV 
INVRS INVT 

To get a list of all group names that begin with a given prefix, use the prefix 
for both arguments or use a wildcard. 

)GRPS INV* 
INVRS INVT 
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Possible Errors Generated 

1 FILE NOT FOUND {FILE NOT FOUND) 

2 2 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 
22 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) 

2 2 INCORRECT PARAMETER (NOT A LETTER) 
5 7 FILE DOES NOT CONTAIN A WORKSPACE 
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) HELP Obtaining Help on the VAX APL Language 
Type 

Query System Command 

Form 

)HELP IstringJ 

Qualifiers 

/ library -.filespec 

Specifies a Help library other than the default APL Help library. This feature 
allows you to write your own Help libraries and reference them through the 
APL )HELP facility. If you want to make your help library the default (and 
thus avoid specifying the /LIBRARY qualifier each time you invoke )HELP), you 
can define the logical name APL$HELP: as the value for filespec. 

The /LIBRARY qualifier must follow directly after the )HELP command, and 
you must specify the colon or equal sign and the VMS file specification. If 
you specify a file that does not exist, APL signals ERROR PROCESSING HELP 
(ERROR OPENING AS INPUT). 

Description 

)HELP provides controlled access to the APL Help facility via the VMS Help 
librarian. 

The APL Help library is a file associated with the VMS logical name 
APL$HELP:. You can define that logical name if you want your own help 
library to be the default. If APL$HELP: is not defined, VAX APL looks for a 
file named SYS$HELP:VAXAPL.HLB, which is placed on your system during 
installation. 

The APL Help Library contains the actual text of the help topics and is 
organized into multiple levels. For example, Q A SS is a secondary level topic 
under QUAD-NAMES, which is a primary level topic. 

You can gain access to the primary level topics by entering the name of a 
primary key as the string parameter. Each of these topics contains explanatory 
text and a menu of secondary level topics. The primary keys include the 
following. 
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Primary Key 



Topic 



Help 

Error-numbers 

Symbols 

Qualifiers 

Quad-names 

System-commands 



General information and menus of other topics 

Error messages beginning with a numeric string 

OAV characters 

Qualifiers beginning with the slash (/) symbol 

System functions and variables beginning with 

the quad (D ) symbol 

System commands beginning with the right 

parenthesis ( ) ) symbol 



To gain access to a secondary level topic, you can enter the name of a primary 
key followed by a space and the name of a secondary key. Use the following 
form: 

)help primary-key secondary-key 

In many cases, you can omit the primary-key parameter and obtain help 
directly from a secondary level; if you specify a system command, system 
function, system variable, qualifier name, or error number, APL generates the 
primary key for you and uses your string as the secondary key. (Note that APL 
generates primary keys only when you use the default APL Help library.) For 
example, you can enter )HELP QMBX and receive information on DMBX without 
enterring )HELP QUAD-NAMES DMBX. The following table describes how APL 
translates secondary key entries: 



INPUT 
Secondary Key 



TRANSLATION 
Primary Key 



null-string 
numeric- string 
atomic- vector-character 
string 
D string 
) string 



Help 

Error-numbers 

Symbols 

Qualifiers 

Quad-names 

System-commands 



APL also performs translations in other instances where the first character 
(not including blanks) following the )HELP command is a character from the 
following table. (These translations do not occur when you have specified 

/LIBRARY.) 
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INPUT TRANSLATION 

Secondary Key Primary and Secondary Keys 



Symbols period 

$ Symbols dollar 

* Symbols divide 

! Symbols shriek 

1 ' Symbols ' 

@ Symbols at sign 

a Symbols lamp 

? Symbols question mark 

( Symbols left parenthesis 



Aside from the instances described above where APL recognizes a string and 
generates the appropriate primary and secondary keys, APL assumes that the 
string you enter is a primary key followed by optional subkeys separated by 
blanks. For example, )HELP ARITHMETIC-FUNCTIONS provides a description 
of arithmetic functions and a menu of subtopics on which you could obtain help. 
Entering )HELP ARITHMETIC-FUNCTIONS FACTORIAL provides information on 
the factorial function. 

Once APL determines a primary key, it translates the key and all related 
subkeys from D A V characters to TTY mnemonics using Q mode; this produces 
keys in a format understood by the Help facility, which then locates the 
appropriate text. This text is then translated from TTY mnemonics toQAV 
characters, converted into uppercase, and then sent to the appropriate output 
destination by APL. (The text is not converted into uppercase in two instances: 
when your terminal is a VT102, VT220, VT240, VT320, VT330, VT340, 
DECterm, VS, or is in TTY mode; and when you execute )HELP with OXQ or 
i.) 

When you request information that currently exists within the APL Help 
Library, the output appears in the following form: 

keyl 
keyl 
key3 

help text 

additional help text (if any) 
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When you request information that currently does not exist within the APL 
Help Library, the output appears in the following form: 

SORRY, NO DOCUMENTATION ON xxx 
ADDITIONAL INFORMATION AVAILABLE ON . . . 

Where xxx is the string you specified when you invoked )HELP, and . . . 
indicates a menu of available help topics. 

APL treats the string parameter as a prefix when it locates a topic in the 
APL Help Library. For example, )HELP QL finds the help file text for all 
QUAD-NAMES beginning with QL. 

The APL Help facility accepts wildcards in the form of the ellipsis (...) and 
pairs of star characters (* * ). (A single * character returns information on the 
* symbol.) For example: 



Command Meaning 



) HELP * * Returns text on all primary key levels. 

)HELP * * . . . Returns all text on all levels. 

)HELP key -name . . . Returns all text on the primary key {key-name 

and all its subkeys). 

Note that you cannot use the ellipsis on secondary (or lower) keys: 

)BELP 
HELP 

The )HELP command provides you with controlled access to the VMS 
HELP librarian to obtain help on various topics related to the 
VAX APL language. APL looks for the file associated with the 
logical name APLiHELP:. If that is not defined, it looks for 
SYSSHELP-.VAXAPL.HLB. This system command accepts terms familiar to 
APL as keys into the APL help library and returns a character vector 
(help text) with embedded Carriage Returns Line Feeds. 

Additional information available: 

APL-applications APL- command- line Arithmetic-Functions Axis 

Comments Editor Error-Humbers Execute-only 

File-System Function-liames Glossary Help Indexing 

Logical-Functions Operators Quad-Sames Qualifiers 

Relational-Functions Specification-Function Statements Symbols 

System-Commands Terminal-Input-Output Terminal-Support 

)HELP + 
SYMBOLS 



Plus TTY mnemonic is + 
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To obtain help on monadic t type )HELP ARITHMETIC-FUNCTIONS CONJUGATE 
To obtain help on dyadic + type )HELP ARITHMETIC-FUNCTIONS ADD 

)HELP 6 

ERROR-NUMBERS 

0006 LABEL ERROR 

Improper use of a colon was detected, or an improper variable 
name was entered as a label. 

Secondary error messages: 

{DUPLICATE LABEL) 

(NAME III USE) 

An attempt was made to use the same identifier for both a label and 
a local symbol or argument, 

(OPERATION SUSPENDED, PENDENT, OR MONITORED] 

An attempt was made to change a label definition in a suspended, pendent, 
or monitored operation. 

hNOTE THAT THE ARGUMENT TO )HELP IS TREATED AS A PREFIX 
nTHERE IS MORE THAN ONE QUAD-NAME THAT STARTS WITH UL 
)HELP UL 

QUAD-NAMES 

UL 



UL - Matched 


Variable 


Name 


Type: 
Forms : 


System Variabl 
UL *■ any-value 


e 




variable-name 


<- UL 


Value 


Domain: 






Resul t 


Domain 


Type: 

Shape: 

Depth: 


Any 
Any 
Any 






Type: 
Rank: 


CI 

l 






Shape: 
Depth: 
Defaul t 


Vt 

1 
1 1 



Character (any when set by user) 
1 (vector) (any when set by user) 
Vector (any when set by user) 

'simple vector) (any when set by user) 

A variable that is used implicitly by WATCH. UL 
contains a character vector showing the name of a watched 
variable that has changed. UL is set implicitly by the 
system when a variable changes, but can also be set by the user. 



Additional information available: 
Errors 



QUAD-NAMES 
ULC 
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DIC - Line Counter 
Type: Niladic System Function 
Form: current-line-number +• QLC 
Result Domain: 

Type: Integer 

Rank: 1 (vector) 

Shape: Vector 

Depth: 1 (simple vector) 
Default Value: Empty 

Vector of line numbers in the state indicator; 
most recently suspended operation appears first. 

Typing -+BLC restarts the most recently suspended 
operation at the beginning of the line where execution 
vas stopped. 



Additional information available: 
Errors 



QUAD-NAMES 

DLX 



ULX - Latent Expression 
Type: System Variable 
Forms: QLX *■ character-vector 

current-value *■ ULX 
Value Domain: 



Type: 


Character 


Shape : 


Vector domain 


Depth: 


or 1 (simple) 


Default 


i i 


suit Domain: 




Type: 


Character 


Rank: 


1 (vector) 


Shape : 


Sector 


Depth: 


l (simple vector) 



Causes expression to be executed automatically 
when workspace is loaded. 

The expression is not executed when you load the 
workspace with the )XL0AD system command. 



Additional information available: 

Errors 

rTHE NEXT EXAMPLE DEMONSTRATES THE /LIBRARY QUALIFIER 
)HELP /LIBRARY=DEV1:[APLGRP.LIBRARY]TEMP.HLB 

HELP 

This is a sample help file. You can modify the VAX APL HELP 
function file or create additional help files. 

For help building library files, see the VMS LIBRARIAN 
REFERENCE MANUAL. 

Additional information available: 

APLHELPJile Assigning_Default_Library 
Library _Source_File LibraryJItility 
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)HELF /LIBRARY^DEVl-.UPLGRP.LIBRARnTEMP.HLB APLHELP 

APLRELP_File 

Certain files may be modified after installation if desired. 

VAXAPL.HLP, the source text of the VAX APL HELP function file, 
is in SYSSLIBRARY. You can add new text to the HELP library. 
Refer to )HELP HELP HOW-TO-BUILD while inside VAX APL for 
instructions on creating the help file. 

Possible Errors Generated 

112 ERROR PROCESSING HELP (ERROR OPENING AS INPUT) 

112 ERROR PROCESSING HELP (ERROR PARSING ARGUMENT TO LIBRARY) 

112 ERROR PROCESSING HELP (INVALID KEY) 

112 ERROR PROCESSING HELP ( TOO MANY HELP KEYS SPECIFIED) 
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) INPUT Diverting Input to Another Device 
Type 



Query/Change System Command 

Form 

) INPUT Ifilespec 1/character-setlJ 

Qualifiers 

/LIST 

The query form of the ) INPUT command. Use /LIST to list the names of the 

currently nested input files. 

/REVERT 

Cancels all nested input files and returns to your terminal as the source of 

input. 



Description 



) INPUT allows you to change the source of APL input from your terminal to 
other devices. Typically, you would select a file (filespec) to be the new source. 
character-set specifies that the file is to be read in a character set other than 
the one you designated for your terminal when you invoked APL. The possible 
values are /TTY, /KEY, /BIT, /COMPOSITE and /APL. 

If no arguments are used, ) INPUT cancels the current input stream and 
returns to the previous input stream on the list. 

The ) INPUT system command is also described in the VAX APL User's Guide 
along with other I/O information. 
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Possible Errors Generated 

1 FILE NOT FOUND ( FILE NOT FOUND) 

14- DEPTH ERROR ( TOO MANY DIVERTED INPUTS) 

22 INCORRECT PARAMETER ( EXTRANEOUS CHARACTER AFTER COMMAND) 

22 INCORRECT PARAMETER ( INVALID CHARACTER SET QUALIFIER) 

3 5 INVALID FILE SPECIFICATION ( WILDCARDS NOT ALLOWED IN FILE 
SPECIFICATION) 
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) LIB Listing Workspace Names 
Type 

Query System Command 

Form 

)LIB tfile-specj 

Description 

)LIB displays a list of workspace or file names located in the area specified. 

If you omit file-spec, )LIB lists all the files on your default device and directory 
area that have the file type .APL (the default for workspace names). If you use 
file-spec, APL lists the names of all selected files, not just workspaces, on the 
selected device and directory. 

You can identify a particular file, or use the wildcard characters * and t- , to 
substitute all or part of the file name or file type; for the version number, only 
* is a valid wildcard character. In the following example, this command lists 
all files on the default device and directory that have a file name beginning 
with the letter W: 

)LIB H*.*;* 

The following command lists the names of all files on the default device in the 
directory [USER.APL]: 

)LIE [USER.APL] 

The file names in the list begin in column 1 and are separated by a Carriage 
Return Line Feed. The list of file names is preceded by a line identifying the 
device and directory, and the list is followed by a line that tells how many files 
were listed. For example: 

)LIB 

Directory DEV1:[APLGRP] 

ALPHA. APL ;1 
CHAR. APL ;1 
GEORGE. APL ;1 
PRIME. APL ;1 
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Total of 4 files. 

)SAVE WSW 
THURSDAY 29-TO7-1990 16:54:45.31 3 BLKS 

)LIB 

DEVI : IAPLGRP1 
ALPHA. APL;1 
CHAR. APL ;1 
GEORGE. APL;1 
PRIME. APL;i 
WSW.APL;1 

Total of 5 files. 

)SAVE USW.VAR 
THURSDAY 29-ffOK-1990 16:54:45.84 3 BLKS 

)LIB WStO.* 

Directory DEV1-.IAPLGRP] 

WSW.APL;1 
WSW.VAR;1 

Total of 2 files. 
)LIB *.* 

Directory DEVlilAPLGRP] 

ALPHA. APL ;1 

CHAR. APL ;1 

GEORGE. APL;1 

LIS+N0R<-1.AAS;1 

LIS<-W0R+IEX.0UT;1 

LIS+W0R+1TMP.AAS;1 

PRIM. API; I 

WRITE+EXAMPLE.C0M;7 

WSH0.APL;1 

WSW.VAR-,1 

Total of 10 files. 

Note that when you execute the )LIB command with no argument, APL passes 
the following command string to VMS for execution: 

DIRECT0RY/C0LUMNS=1/HEADING/TRAILING * .APL; * 
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If you include an argument with )LIB, that argument is substituted for 
* . A PL ; * in the command string passed to VMS. The argument may be no 
more than 95 characters long (after translation to ASCII), not including leading 
white space (spaces or tabs before the argument begins), but including all other 
white space within the argument. For example: 

) LIB I PROTECT ION USHO.* 

Directory DEV1-.IAPLGRP] 

WSHO.APL-,1 {RUED, RUED, RE,) 

USW.VAR-,1 (RUED, RUED, RE,) 

Total o/ 2 files. 

The )LIB command uses the DCL command DIRECTORY. This is true even 
if you have a symbol definition for DIRECTORY that has different qualifiers. 
For more details about the DCL command DIRECTORY, see the VMS DCL 
Dictionary. 

Possible Errors Generated 



2 2 INCORRECT PARAMETER (LINE TOO LONG TO TRANSLATE) 
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)LOAD Retrieving a Workspace 
Type 

Workspace Manipulation System Command 

Form 

)LOAD wsname 

Qualifiers 

/PASSWORD [:[pw]] 

If you use a password when the workspace is saved, you must specify it 

when you perform a load operation or APL will not retrieve the workspace. A 

/PASSWORD or /PASSWORD: specification that is not followed by a password is 

ignored. 

/CHECK 

The optional /CHECK qualifier causes APL to examine the workspace for 
possible corruption (damage to the internal structure of the workspace). If 
damage is detected, a message is displayed and APL tries to recover as much 
information as possible from the workspace and continues the load. The 
recovered workspace may be missing APL variables, user-defined operations, 
individual lines of user-defined operations, and other APL objects that were 
damaged. The user must determine what named objects have been removed 
from the workspace. You must use the ) SA VE command if you want to 
maintain an undamaged version of the recovered workspace. 

Description 

)LOAD makes wsname the active workspace by replacing, and thus destroying, 
the contents of the currently active workspace. If the workspace named by 
wsname is larger than the current )MAXCORE setting, APL increases the 
setting and loads the workspace. 

The file specification you give for wsname must include at least a file name. 
APL will assume default values for the rest of the specification; that is, it 
assumes the file type .A PL, the current user device and directory, and an 
empty password. 
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When you load a workspace, the )LOAD system command responds by 
displaying the word SA VED, followed by the time and date when the workspace 
was saved, followed by the size (in disk pages) of the newly active workspace. 
If the newly active workspace contains a suspended operation, APL also prints 
a star. If the newly active workspace is larger than the current setting for 
MAXCORE, APL prints the message NEW MAXCORE IS nnnP, where nnn is the 
new size of maxcore, and P indicates that the size is measured as pages of 
memory. The ) WSID value of the loaded workspace is the value you specified 
for wsname. 

The D QLD system function (see Chapter 2) performs the same operation as the 
)LOAD command, but does not display the verifying messages. 

The verifying messages for the )LOAD and )SAVE system commands are very 
similar. The only difference is that when you load a workspace, the message 
includes the word SAVED. You can use this difference to distinguish between a 
workspace that has just been loaded and a workspace that has just been saved. 
For example: 

VFRY 
[1] M <- UXQ 'SAVE ROAR') 
[2] 'MESSAGE IS ' ; M 
[3] V 

)WSID FRY 
WAS CLEAR US 

FRY 
MESSAGE IS THURSDAY 8-ffOf-1990 17:12:33. U 16 BLKS 

)L0AD ROAR 
MESSAGE IS SAVED THURSDAY 8-JV0V-1990 17:12:33.14 16 BLKS 

M 
SAVED THURSDAY 8-JV07-1990 17:12:33. It 16 BLKS 

In this case, the user executes the ) SA VE command from within the function 
FRY. APL saves the workspace and assigns the verifying message of the 
) SA VE command to the variable M. Next, the user loads the workspace. APL 
immediately continues execution of the function and assigns the verifying 
message of the )LOAD command to the variable M. 

When you load a workspace that was saved inside D input, APL removes the 
pendent □ input from the state indicator stack. If the Q input was executed 
from within an operation, APL suspends the operation after removing the 
pendent Q input from the stack. 

If the D LX system variable (see Chapter 2) has a value in the workspace, it is 
executed when the workspace is loaded, unless the top of the state indicator 
stack contains an execute function, or unless the workspace was saved in 
function-definition mode (if it was, you remain in function-definition mode after 
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the workspace is loaded). If the workspace was saved inside D input, the ULX 
expression is executed only after APL removes the pendent Q input from the 
state indicator stack. 

Examples: 

)L0AD WS35 _ 
SAVED THURSDAY 8-JVOF-1990 17:12:11.52 41 BUS 

)L0AD SYSSSCRATCH-.TICTAC 
SAVED THURSDAY S-NOV-1990 17:11:59.28 41 BUS 

fiJEt) HAS A SUSPENDED OPERATION 

)L0AD JEN 
SAVED THURSDAY 8-NOV-1990 17:04:23.38 42 BLKS* 

) CLEAR 
CLEAR US 

QLX *■ " 'USE APL_LASER PRINTER' • ' 

)L0AD SQUARE 
SAVED THURSDAY 8-NOV-1990 17:03:11.46 11 BLKS 

SQUARE 

)WSID ROOT 
MS SQUARE 

)SAVE ROOT 
THURSDAY 8-NOV-1990 17:27:40.51 12 BLKS 

)L0AD ROOT 
SAVED THURSDAY 8-NOV-1990 17:27:40.51 12 BLKS* 

Possible Errors Generated 

2 2 INCORRECT PARAMETER 

2 2 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) 
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) MAX CO RE Determining the Maximum Workspace Size 
Type 

Query/Change System Command 

Form 

)MAXCORE InJ 

Default in Clear Workspace 

1024P / 1048576P 

Description 

As an action command, )MAXCORE changes the current setting for the 
maximum workspace size to the value specified (re) and displays the previous 
) MAX CORE setting. As a query command, ) MAX CORE returns the current 
maximum workspace size and the system maximum workspace size. 

You may not set the current maximum workspace size to a value smaller than 
the amount currently in use, or to a value less than 40, which is the minimum 
value of re for all new workspaces. Also, you may not set the maximum size to a 
value larger than the system maximum. Note that, depending on your system 
resources, you may not have access to the maximum amount of memory. 

Although the number of pages (P ) appears in the display, you do not type P in 
the command string. For example: 

)MAXC 
1024P/ 104-8576P 

)MAXC 2000 
WAS 1024P/ 1018576P 

)MAXC 
2000P/ 1048576P 

Possible Errors Generated 

2 2 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 
2 2 INCORRECT PARAMETER {ILL FORMED NUMERIC CONSTANT) 
2 2 INCORRECT PARAMETER (PARAMETER OUT OF RANGE) 
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) MINCORE Determining the Minimum Workspace Size 
Type 

Query/Change System Command 

Form 

) MINCORE InJ 

Default in Clear Workspace 

40P 

Description 

) MINCORE displays or changes the current minimum workspace size (in 
pages). As an action command, ) MINCORE changes the current setting for 
the minimum workspace size to the value specified (n) and displays the 
previous setting. Legal values for the ) MINCORE setting are through the 
current )MAXCORE value. As a query command, ) MINCORE returns the current 
minimum workspace size. 

The ) MINCORE system command is useful in dealing with large arrays or in 
performing operations that require large amounts of intermediate storage. 
Such operations can make the workspace continually expand, thus slowing 
the processing and fragmenting of the workspace. You can improve system 
efficiency by using ) MINCORE to ensure that a reasonable amount of memory is 
available at the beginning of the operation. 

Generally, the ) MINCORE setting does not change when you load a workspace. 
However, depending on the characteristics of the loaded workspace, the 
) MINCORE setting may be greater than the amount of available memory. In 
this case, ) MINCORE is reset to the default when the )LOAD succeeds (no error 
is signaled). 

Examples: 

)MINC 
32P 

)MINC 100 
WAS 32P 
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Possible Errors Generated 

22 INCORRECT PARAMETER {EXTRANEOUS CHARACTERS AFTER COMMAND) 
2 2 INCORRECT PARAMETER (ILL FORMED NUMERIC CONSTANT) 
22 INCORRECT PARAMETER (PARAMETER OUT OF RANGE) 
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) MON Returning to Operating System Command Level 
Type 

System Action System Command 

Form 

)MON 

Description 

) MON returns control to operating system command level. It does not save 
the active workspace, but if UAUS is set (see Chapter 2), the workspace is 
automatically saved. The )MON command does not close open files, but it does 
flush the file buffers. 

When you use )MON to leave APL, you can return to APL by typing the DCL 
command CONTINUE. If you intend to return to APL, be careful not to destroy 
your memory image while you are at DCL level. This situation could occur if 
you issue a command that runs a program. 

The )MON command has limited value because most DCL commands do run 
a program and thus will destroy the APL image. If you want to return to 
the DCL command level to run other programs, you should use the ) PUSH or 
)D0 command. If you want to return to another process, you should use the 
) ATTACH command. 

Possible Errors Generated 

22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 
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) NMS Displaying Names in the Symbol Table 
Type 



Query System Command 

Form 

) NMS frstart-stringfrstop-stringjl 

Qualifiers 

/wsiD: wsname 

Allows you to list the names in a nonactive workspace, wsname specifies the 

workspace. 

/PASSWORD: Jpiyfl 

Specifies the password used when the nonactive workspace was saved. 



Description 



)NMS displays all the names in the symbol table in QAV order. The result is a 
combination of the same information obtained by the )VARS, )FNS, )OPS, and 
) GRPS commands. 

By default, APL displays the names from the currently active workspace. The 
optional /WSID qualifier allows you to specify a nonactive workspace. If the 
nonactive workspace was saved with a password, you must also specify the 
/PASSWORD qualifier. 

The optional string parameters identify starting and stopping points for 
the list. When you specify the string parameters, you can use the * and * 
wildcards. The objects are listed in UAV order, separated by tabs. Each output 
line in the list begins in column 1. 

Note that the wildcard determines the start-string. There is no wildcard for 
the stop-string. 
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The following name classes are possible: 



Value Meaning 



o Name not in use 

2 Variable name 

3 Function name 
4- Operator name 

" "+ Group name 



A symbol has a name class of when it has no value. Such a symbol may be 
listed in the symbol table because it is currently referenced in a user-defined 
operation (either a function or operator) or was previously used and has since 
been erased. For example: 

)L0AD NAMES 
SAVED THURSDAY 8-JV07-1990 17:44:43.63 15 ELKS 

)GRPS 
LABI RECAP REPLACE VERTICAL 

)VARS 
A B LAT VET 

)FNS 
ADD 

)NMS 
A. 2 ADD. 3 B.2 DC.O DONE.O DOWN.O LABl.'H LAT. 2 

NEW.O OLD.O OUT.O RECAP.'H REPLACE.'^ TEST .0 

UP.O VERTICAL. "4 VET. 2 

If you use ) NMS with no parameters, APL displays all the symbols in the 
workspace. If you use the optional string parameters, you can specify a 
particular section from the list of symbol names. For example, all the names 
starting with B through those starting with LA. If you include just one 
argument, APL uses Z as the default for the second string. To get a list of all 
symbol names that begin with a given prefix, use t$te prefix for both arguments 
or use a wildcard. For example: 
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)L0AD NAMES 
SAVED THURSDAY 8-N0V-1990 17:44:13.63 15 BLKS 

)NMS B LA 
B.2 DC.Q DONE.Q DOUN.O LABI. 4 LAT.2 

)NMS R 
RECAP.'l REPLACE.'^ TEST.O UP.O VERTICAL. 4 VET. 2 

)NMS VE VE 
VERTICAL.'^ VET. 2 

)NMS VE* 
VERTICAL. H VET. 2 

Possible Errors Generated 

1 FILE NOT FOUND (FILE NOT FOUND) 

2 2 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 
22 INCORRECT PARAMETER (FILE SPECIFICATION IS MISSING) 

2 2 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) 
2 2 INCORRECT PARAMETER (NOT A LETTER) 
57 FILE DOES NOT CONTAIN A WORKSPACE 
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) OFF Terminating the APL Session 
Type 

System Action System Command 

Form 

)OFF iHOLD | LOGOUT J 

Default in Clear Workspace 

HOLD 

Description 

) OFF terminates an APL session. 

If you specify the HOLD parameter (HOLD is the default), APL terminates your 
session and returns you to DCL command level. If you specify the LOGOUT 
parameter, APL not only terminates your session, but logs you off the system. 

The )OFF command destroys the currently active workspace, deletes the QAUS 
file, closes all open files, and resets the terminal characteristics to the system 
settings. When you use ) OFF, you cannot return to APL by enterring the DCL 
command CONTINUE. 

The ) OFF command displays several lines of information before terminating 
the session. The lines contain the following: 

• Your terminal identification 

• Current time 

• Current date 

• Length of time connected to APL 

• Amount of computer CPU time used inside APL 

• Number of APL statements executed 

• Number of APL operations executed 

• Number of page faults while inside APL 

• Number of buffered 10 and number of direct 10 while inside APL 
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Examples: 



)0FF LOGOUT 
SYSHNPUT: THURSDAY 8-ffO7-1990 17:18:59.32 
CONNECTED 00:00:00.98 CPU TIME 00:00:00.37 
STATEMENTS OPERATIONS 
170 PAGE FAULTS 21 BUFFERED 10 9 DIRECT 10 

)OFF HOLD 
SYSHNPUT: THURSDAY 8-NOV-1990 17:50:13.15 
CONNECTED 00:00:00.98 CPU TIME 00:00:00.38 
STATEMENTS OPERATIONS 

154 PAGE FAULTS 21 BUFFERED 10 9 DIRECT 10 
$ 

Possible Errors Generated 



2 2 INCORRECT PARAMETER {EXTRANEOUS CHARACTERS AFTER COMMAND) 
22 INCORRECT PARAMETER (UNRECOGNIZED QUALIFIER KEYWORD) 
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) OPS Displaying a List of Operators 
Type 

Query System Command 

Form 

) OPS Istart-stringlstop-stringJJ 

Qualifiers 

/wsiD: wsname 

Allows you to list the user-defined operators denned in a nonactive workspace. 

wsname specifies the nonactive workspace name. 

/ PASSWORD :pw 

Specifies the password used when the nonactive workspace was saved. 

Description 

) OPS displays a list of the global names used as user-defined operator names 
in a workspace. By default, APL displays the list from the currently active 
workspace. The optional / WSID qualifier allows you to specify a nonactive 
workspace. If the nonactive workspace was saved with a password, you must 
also specify the / PASSWORD qualifier. 

The optional string parameters identify starting and stopping points for 
the list. When you specify the string parameters, you can use the * and 4- 
wildcards. The objects are listed in QAV order, separated by tabs. Each output 
line in the list begins in column 1. 

Note that the wildcard determines the start-string. There is no wildcard for 
the stop-string. 

If you use ) OPS with no parameters, APL displays all the global operator 
names in the workspace: 

)0PS 
ALPH HILB INVRS INVT LSQ 
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If you include just one argument, APL uses Z as the default for the second 

string: 

)0PS IN 
INVRS INVT LSQ 

)0PS INV INV 
INVRS IN VI 

To obtain a list of all user-defined operator names that begin with a given 
prefix, use the prefix for both arguments or use a wildcard: 

)0PS INV* 
INVRS INVT 

Possible Errors Generated 



1 FILE NOT FOUND (FILE NOT FOUND) 

22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 
22 INCORRECT PARAMETER (FILE SPECIFICATION IS MISSING) 

2 2 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) 
2 2 INCORRECT PARAMETER (NOT A LETTER) 

5 7 FILE DOES NOT CONTAIN A WORKSPACE 
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) ORIGIN Determining the Index Origin 
Type 

Query/Change System Command 

Form 

) ORIGIN flnj 

Default in Clear Workspace 

i 

Description 

) ORIGIN displays or changes the setting of the index origin (D 10). 

The index origin (n in the form) can be either or 1; its setting determines 
whether the values of an array are indexed beginning with position or 1. 

Executing the ) ORIGIN in change mode has the same effect as assigning a 
value to the D 10 system variable (see Chapter 2). 

Examples: 

i5 

12 3 4 5 

) ORIGIN 
MS 1 

i5 
12 3 4 

) ORIGIN 


Possible Errors Generated 

2 2 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 

2 2 INCORRECT PARAMETER (ILL FORMED NUMERIC CONSTANT) 

2 2 INCORRECT PARAMETER (SYSTEM VARIABLE VALUE MAY ONLY BE OR 1) 
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) OUTPUT Diverting Output to Another Device 
Type 

Query/Change System Command 

Form 

) OUTPUT Ifilespec I /character- set J 

Qualifiers 



/APPEND 

Specifies that you want to add data to the end of an existing file. If you specify 

filespec without the /APPEND qualifier, APL creates a new file. 

/DISPOSE: { KEEP | DELETE \ PRINT | SUBMIT \ PRINTDELETE | 
SUBMITDELETE} 

Specifies whether the value of filespec is a temporary or permanent file. 
/DISPOSE -.KEEP, which is the default, means the file is permanent; 
/DISPOSE -.DELETE means the file will be deleted when it is closed. 
/DISPOSE-.PRINT sends the file to a print queue (SYS$PRINT) when the file is 
closed, and /DISPOSE-.SUBMIT sends the file to a batch queue (SYS$BATCH) 
when the file is closed. PRINTDELETE and SUBMITDELETE send the file to the 
appropriate queue and then delete the file when the job is finished. 

/LIST 

This is the query form. Allows you to display the diverted output file on one 
line and SYS$OUTPUT (the VMS name for your default output stream) on the 
next line (or just SYS$OUTPUT, if output is not being diverted). 

/REVERT 

Causes the return of system output from the diverted destination to your 

terminal. This is the same as using ) OUTPUT with no qualifiers. 

/SHADOW 

Allows you to display the diverted output on your terminal as well as sending 
it to a file. Otherwise, no system output is displayed except for system prompts 
and echoed input. 

If you want to begin shadowing output that is already diverted, you can reenter 
the original ) OUTPUT command and add the /SHADOW and /APPEND qualifiers. 
If you want to discontinue shadowing while keeping the same diverted output 
stream, you can reenter the original ) OUTPUT command with the omission 
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of the /SHADOW qualifier and the addition of the /APPEND qualifier. (You can 
change any of the original arguments or qualifiers at this time. If you omit 
information that you specified in the original ) OUTPUT command, APL selects 
any default values that may be applicable. For example, output diverted from 
an APL terminal with the /TTY qualifier defaults to the APL character set if 
you do not reenter the /TTY qualifier.) 

Description 

) OUTPUT allows you to change the destination of output to a device other than 
your terminal. Typically, you send the output to a file or to another terminal. If 
the output is sent to a file, you can specify that you want to write the diverted 
output in a character set other than the one you designated for your terminal 
when you invoked APL. The possible values for character-set are /TTY , /KEY , 
/BIT, /COMPOSITE, and I APL. 

) OUTPUT with no arguments or qualifiers causes the system output to return 
from the diverted destination to your terminal. This is the same as using the 
/REVERT qualifier. 

When you use ) OUTPUT, the output file has the appearance of a normal 
terminal display containing input lines and the resulting output. However, at 
your terminal the display is different. The only output that APL generates 
at your terminal is echoed input and APL prompts. APL echoes any input, 
whether it comes from your terminal or a file, and APL displays the usual 
6-space prompt to signal the completion of a task. In fact, all APL-generated 
prompts (such as the Q SF prompt and function editor prompts) are still 
displayed at the terminal. If you want to see a normal display at your 
terminal, use the /SHADOW qualifier (see below). 

Note that ) OUTPUT files cannot be nested. 

If you enter either a weak or strong attention signal while output is being 
diverted from your terminal, APL responds by displaying output on your 
terminal as well as in the diverted stream, just as if you had specified 

/SHADOW. 

The ) OUTPUT system command is also described in the VAX APL User's Guide 
along with other I/O information. 
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Possible Errors Generated 

2 2 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 

22 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) 

22 INCORRECT PARAMETER (REDUNDANT KEYWORD OR QUALIFIER) 

33 10 ERROR (INVALID WILDCARD OPERATION) 
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) OWNER Displaying Information About Workspace Creation 
Type 

Query System Command 

Form 

) OWNER 

Description 

) OWNER displays information about the active workspace at the time it was 
created. A workspace is created when it is saved. The clear workspace is 
created when the ) CLEAR system command is given. 

The result of the ) OWNER appears in the following form: 

created on day dd-mmm-yyyy hh:mm:ss.tt by name [uic] at dev: with Iv.u-edit 

day dd-mmm-yyyy hh:mm:ss.tt is the day, date and time of creation 

name is the user name of the creator 

uic is the user identification code of the creator 

dev: is the terminal device name used to create the workspace 

Iv.u-edit is the version of APL used to create the workspace (see the 

description of Q VERSION in Chapter 2) 

Examples: 

) CLEAR 
CLEAR US 

) ONMER 
CREATED ON THURSDAY 8-TO7-1990 18:11:49.32 BY 
[APLGRP,USER] AT WITH V3. 2-834 

)SAVE USER IMS 
THURSDAY 8-TO7-1990 18:11:49.51 3 BLKS 

)L0AD USER1US 
SAVED THURSDAY 8-ff07-1990 18:11:49.51 3 BLKS 

) OWNER 
CREATED ON THURSDAY 8-iV07-1990 18:11:49.51 BY 
[APLGRP,USER1 AT WITH 73. 2-834 



3-68 APL Reference Manual 



System Commands 

) OWNER Displaying Information About Workspace Creation 



Possible Errors Generated 



2 2 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 
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) PASSWORD Workspace Password 
Type 

Query/Change System Command 

Form 

) PASSWORD RpwJ 

Default in Clear Workspace 

Empty 

Qualifiers 

/PASSWORD -Jpwl 

Specifies the password associated with the active workspace. 



Description 



) PASSWORD displays or changes the password associated with the active 
workspace. 

APL passwords are eight characters long, and the password you supply must 
be a valid APL identifier. Passwords longer than eight characters are truncated 
on the right; passwords with fewer than eight characters are padded on the 
right with blanks. 

If you do not change the password, the form of the ) PASSWORD display is as 
follows: 

/PASSWORD: pw 

If you do change the password, the form of the ) PASSWORD display is as follows: 

WAS /PASSWORD: pw 

If the password is empty, the display is one of the following: 

/PASSWORD: WAS /PASSWORD: 

When you use ) PASSWORD to change the password, you can specify the 
new password directly after the ) PASSWORD, or you can specify it following 
/PASSWORD. For example: 
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) PASSWORD SESAME 
HAS /PASSWORD: 

^PASSWORD NILE BE TRUNCATED TO 8 CHARACTERS 

) PASSWORD I PASSWORD : OPEN SESAME 
WAS /PASSWORD -.SESAME 

) PASSWORD /PASSWORD: 
WAS / PASSWORD: OPEN SESA 

) PASSWORD 
/PASSWORD: 

To load or copy objects from a workspace with a nonblank password, you must 
include the password for the workspace in the command string. 

Possible Errors Generated 

2 2 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 
2 2 INCORRECT PARAMETER (ILL FORMED NAME) 
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) PCOPY Copying from a Workspace with Protection 
Type 

Workspace Manipulation System Command 

Form 



) PCOPY wsname llist3 

Qualifiers 

/ CHECK 

The optional / CHECK qualifier causes APL to examine the workspace for 
possible corruption (damage to the internal structure of the workspace). If 
damage is detected, a message is displayed and APL tries to recover as much 
information as possible from the workspace and to continue the copy. The 
recovered workspace may be missing APL variables, user-defined operations, 
individual lines of user-defined operations, and other APL objects that were 
damaged. The user must determine what named objects have been removed 
from the workspace. 

/PASSWORD I :Ipw/fl] 

Specifies the password used when wsname was saved. 

Description 

) PCOPY (protected copy) is the same as the ) COPY system command, except 
that ) PCOPY does not replace objects in the active workspace with objects of 
the same name in the copy workspace. Instead, APL returns the message NOT 
COPIED : along with the names of the objects affected. 

When copying groups, the ) PCOPY command does not copy any members of the 
group that have the same name in both workspaces. If the group name itself is 
the same as a group name in the active workspace, ) PCOPY does not copy the 
group name, nor any members of the group. 

The ) PCOPY system command performs the same operation as the DQPC 
system function (see Chapter 2), but DQPC does not display messages to verify 
the success of the copy. 
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Example: 

) PCOPY VARS A T 
SAVED TUESDAY 6-ff07-1990 18:21:58.41 13 BLKS 

FOUND: T 
HOT COPIED: A 

Possible Errors Generated 

2 2 INCORRECT PARAMETER 

2 2 INCORRECT PARAMETER (ILL FORMED NAME) 

2 7 LIMIT ERROR (ARGUMENT STRING IS TOO LONG) 

8 3 DAMAGED WORKSPACE HAS BEEN CORRECTED (SOME SYMBOLS MAY HAVE 
BEEN ERASED) 
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) PUSH Interacting with Operating System Programs 
Type 

System Action System Command 

Form 

) PUSH Icommand-stringJ 

Qualifiers 

/NO KEY PAD 

Specifies that you do not want the keypad characteristics of the current process 
to be available to the new subprocess. The default is that the characteristics 
are available. 

/NOLOGICALS 

Specifies that you do not want the logical name table from the current process 

to be available to the new subprocess. The default is that the table is available. 



/NOSYMBOLS 

Specifies that you do not want the global and local symbol table (defined at the 
DCL level) from the current process to be available to the new subprocess. The 
default is that the symbol table is available. 

/NOTIFY 

Determines whether VMS broadcasts a message to your current process when 
the new subprocess completes or aborts. If you are executing the ) PUSH 
command from the batch mode, you cannot use the /NOTIFY qualifier. Note 
that you can use /NOTIFY only when you specify the /nowai t qualifier. 

/ pro cess : process-name 

Specifies the name for the new subprocess. If you do not use / NOWAI T, and you 
use the DCL command ATTACH rather than the LOGOUT command to return 
to APL, you can later use the ) ATTACH command with the process name that 
you specify. 

/NOWAIT 

Allows you to create a detached subprocess. When you specify /NOWAIT, control 
returns to APL when the subprocess begins execution, and the subprocess 
continues to execute in the background. Note that if the subprocess uses any 
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terminal I/O, it becomes mixed with any terminal I/O used by your current 
process. 



Description 



) PUSH interrupts the APL session, creates a VMS subprocess, and puts you at 
DCL command level without terminating the APL session. You can perform 
any operation at the DCL command level; when you are finished, you can 
return to APL at the point you left off. 

Note that if you use an invalid qualifier when you specify )PUSH, APL sends 
the unrecognized characters to the subprocess command level along with the 
command string. 

If you want to display the process name of any subprocess owned by the 
current process, use the DCL command SHOW PROCESS/SUBPROCESSES 
(for more details, see the VMS DCL Dictionary). 

When you use ) PUSH without a command string, you remain at DCL command 
level until you enter LOGOUT to return to APL. When you use ) PUSH with a 
command string (do not enclose the string in quotation marks), VMS executes 
the command string and then automatically returns control to APL. The 
command string must be no longer than 132 characters (after translation to 
ASCII), not including leading white space (spaces or tabs before the argument 
begins), but including all other white space within the argument. 

For example, entering ) PUSH and the DCL command SHOW TIME, and then 
LOGOUT has the same effect as entering ) PUSH with the command string 

SHOW TIME: 

)PUSH 

$SH0W TIME 

23-NOV-1990 13:32:42 
$ LOGOUT 

Process USER1 logged out at 23-NOV-1990 13:33:13 

)PUSH SHOW TIME 
23-AW-1990 13:33:iH 

While you are at DCL command level, your terminal is in ASCII rather than 
APL mode, and your terminal characteristics (such as output line width) revert 
to the system settings. When you return to APL, the APL character set is 
restored, and your Q PW setting is the same as it was before you executed the 
) PUSH command (although the default for D PW changes if you changed your 
system terminal width (see Chapter 2 for details). However, other terminal 
characteristics you may have changed at DCL command level (for example, the 
QGAG setting, or the ability to input lowercase characters) remain changed. 
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APL makes no attempt to recover the output from any of the work you do at 
DCL command level. For example: 

TIME +■ i ' ) PUSH SHOW TIME ' 

2Z-N0V-1990 13:1*0:34 

11 VALUE ERROR (REQUIRED VALUE HOT SUPPLIED BY EXECUTE) 
TIME <- i.')PUSH SHOW TIME' 

A 

Here, APL executes the ) PUSH command, and VMS displays the result of the 
SHOW TIME command. But APL does not recover the output and cannot 
assign the value to the variable TIME. 

For more details about VMS subprocesses, see the VMS DCL Dictionary. 

Possible Errors Generated 



22 INCORRECT PARAMETER {ILLEGAL ASCII CHARACTER) 

22 INCORRECT PARAMETER (MISSING ARGUMENT) 

2 2 INCORRECT PARAMETER (NOKEYPAD QUALIFIER REPEATED) 

22 INCORRECT PARAMETER (NOLOGICALS QUALIFIER REPEATED) 

2 2 INCORRECT PARAMETER (NO SYMBOLS QUALIFIER REPEATED) 

2 2 INCORRECT PARAMETER (NOTIFY QUALIFIER REPEATED) 

22 INCORRECT PARAMETER (NOWAIT QUALIFIER REPEATED) 

2 2 INCORRECT PARAMETER (PROCESS NAME QUALIFIER REPEATED) 

7 3 SUBPROCESS ERROR (COMMAND BUFFER OVERFLOW SHORTEN EXPRESSION 

OR COMMAND LINE) 



3-76 APL Reference Manual 



System Commands 

) SA VE Saving a Copy of the Active Workspace 



) SA VE Saving a Copy of the Active Workspace 
Type 

Workspace Manipulation System Command 

Form 

)SAVE IwsnameJ 

Qualifiers 

/CHECK 

The optional / CHECK qualifier causes APL to examine the workspace for 
possible corruption (damage to the internal structure of the workspace). When 
/ CHECK is specified on ) SA VE, APL checks for possible damage before saving 
the current workspace on disk. If there is damage, APL signals an error and 
aborts the execution of )SAVE. If this occurs, use )SAVE without /CHECK to 
save the damaged workspace; use )LOAD with /CHECK to recover as much as 
possible from the damaged workspace and determine what APL objects have 
been lost from the damaged workspace. You must use the )SAVE command if 
you want to maintain an undamaged version of the recovered workspace. 

I MAXLENlinJ 

The optional /MAXLEN qualifier allows you to specify the maximum record 
length, n (in bytes), to be used to save the workspace. If you omit /MAXLEN (or 
specify it without an argument), APL uses the value of Q DHL (see Chapter 2) 
as the maximum record length. 

/password I :lpw$$ 

The ) SA VE system command allows you to specify a password for your 
workspace. The default is an empty password (eight blanks). If you save a 
workspace that has a password - either one you specify with ) SA VE or one 
specified earlier by the ) PASSWORD or )WSID command — you have to specify 
the password when you load or copy the workspace. 

Description 

) SA VE saves a copy of the active workspace in a file specified by wsname. If 
you omit wsname, the file is saved with the name currently returned by ) WSID. 
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The ) SA VE command displays the time and date the workspace is saved, the 
number of disk blocks required to store the workspace, and the workspace 
identification (either the name currently returned by ) WSID, or the name you 
specify as wsname). )SAVE appends a star (* ) to the message if the saved 
workspace contains a suspended operation. 

When you save a workspace, you have the option of saving it under its current 
name — the name returned by ) WSID — or renaming it. However, APL does not 
save a workspace under a name that already exists in your storage area, unless 
the ) WSID is that name. If you specify a new name with the )SAVE command, 
you not only store your active workspace under that name, but you also change 
the name of the currently active workspace to the new name specified. 

If your current ) WSID is the same as a workspace you have already saved, APL 
creates a new version of the file. Both the old and new files are available on 
the appropriate storage device; however, the new file is considered the current 
version and has a version number one greater than that of the old file. 

APL does not save a clear workspace. If your workspace is clear, you must first 
give it a name with the ) WSID command, or you must use the ) SA VE command 
with a workspace name. 

If you specify a password using ) PASSWORD or ) WSID, but then save the 
workspace using the wsname parameter, the workspace is saved with an empty 
password (unless you specify a new one with ) SA VE). For example: 

)WSID MYWS /PASSWORD -.SESAME 
WAS EXAMPLE 

oCHANGE THE WSID 
)SAVE MIWS 
THURSDAY 8-NOV-1990 19:42:58.52 15 BLKS 

)WSID 
MYWS 

p PAS SWORD CHANGED TO EMPTY 
) PAS SWORD 
/PASSWORD: 

aNO NEED FOR A PASSWORD WHEN LOADING 
)L0AD MYWS 
SAVED THURSDAY 8-tf07-1990 19:42:58.52 15 BLKS 

You can save a workspace while there is a suspended operation on the top of 
the SI stack. When you load the workspace, the operation is still suspended; it 
does not continue automatically. You can cause an automatic startup by using 
the D LX system variable (see Chapter 2). 
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If you execute a )SAVE command within an operation, for example, with D XQ 
' ) SAVE' , APL saves the workspace, displays the time and date, and continues 
executing the operation. The next time you load that workspace, APL displays 
a slightly different message (see )LOAD for details) and begins the session by 
executing that particular operation after the D XQ ') SAVE '.It does not execute 
DLX, because QLX does not execute if the loaded workspace is in function- 
definition mode, or if the operation at the top of the state indicator stack is 
pendent. 

Examples: 

) CLEAR 
CLEAR US 

)WSID 
CLEAR US 

)SAVE 
60 WS NOT SAVED, THIS WS IS CLEAR WS 

)SAVE 

A 

)WSID WS30 
HAS CLEAR WS 

)SAVE 
THURSDAY 8-^07-1990 19 : 46 :08 .95 3 BLKS WS30 

)WSID WS 10 
WAS WS30 

)SAVE 

THURSDAY 8-AT07-1990 19:46:09.24- 3 BLKS WS10 

)WSID 6/S30 
WAS WS10 

)SAVE WS10 
60 WS HOT SAVED, THIS WS IS WS30 

)SAVE WS10 

A 

)WSID WS35 
WAS WS30 

Possible Errors Generated 

2 2 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 
2 2 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) 
5 9 WS NOT SAVED, THIS WS IS CLEAR WS 
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) SI Displaying the State Indicator 
Type 

Query System Command 

Form 

)SI 

Description 

) SI displays the state indicator of the active workspace. The state indicator 
contains the status of the execution of user-defined operations, quad input 
requests, and execute functions. 

For user-defined operations, APL displays the operation name followed by, 
within brackets, the line and statement numbers at which the operation 
stopped executing. No statement number is displayed if the statement at 
which execution stopped is the first or only statement on the line. If a 
statement number is displayed, it is separated from the line number by a 
diamond (o ) character. A star following the bracketed line and statement 
number indicates that the operation is currently suspended; no star indicates 
that the operation is pendent. For example: 

)SI 
F[2] * 
ff[302] 

In this example, the pendent operation G stopped executing at statement 2 on 
line [3] and is currently waiting for operation F, which was suspended at line 

[2]. 

Pendent quad input requests are indicated by a D character. For example: 

A+-U 
D: 

)SI 

D 

D: 

First, the ) SI display shows that the quad input request is pendent; then, APL 
displays D : to reprompt for quad input. 
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Pendent execute functions are indicated by the □ XQ or 4 characters. For 
example: 

UXQ <)SI' 
UXQ 

)SI 

(There is no output) 

In this example, the ) SI display indicates that an execute function is pendent. 
This occurs because APL executes expressions from right to left, and the 
output from ) SI is displayed before the execute function is considered to have 
completed. Afterwards, the state indicator is clear. 

The order of display in the ) SI list is significant; the operation or quad input 
request that was most recently active is listed first, the next most recent 
request is listed second, and so on. 

Locked operations in the state indicator are flagged with a V character, and no 
line number is displayed. 

You can clear individual operations from the state indicator by using the 
branch function (->-) to restart or terminate suspended operations, or you can 
use the system function □ RESET or )SIC to clear the state indicator entirely. 
When the state indicator is clear, ) SI returns no result. For more information, 
see the VAX APL User's Guide 

Possible Errors Generated 

22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 
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) SIC Clearing the State Indicator 
Type 

APL Action System Command 

Form 

)SIC 

Description 

) SIC clears the state indicator. Once cleared, the state indicator shows 
no suspended operations and no pending quad input requests or execute 
functions. After you use )SIC, the )SI, )SINL, and )SIS system commands 
do not return a value. The )SIC system command behaves in the same 
manner as the D RESET system function (see Chapter 2), and they can be used 
interchangeably. 

) SIC does not return a value. 

Possible Errors Generated 

22 INCORRECT PARAMETER {EXTRANEOUS CHARACTERS AFTER COMMAND) 
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) SINL Displaying the State Indicator and Local Symbols 
Type 

Query System Command 

Form 

)SINL 

Description 

)SINL displays the same information as )SI. This includes the status of 
the execution of user-defined operations, quad input requests, and execute 
functions. In addition, ) SINL lists the local symbols of each operation, and 
displays the argument expression of any pending execute function. Local 
symbols in locked operations (flagged with a ¥ character) are not displayed. 

For example: 

)SINL 
F[2] * R A B 
G[302] * T C A D 

Here, the pendent operation G has the local symbols T , C , A , and D . The 
suspended operation F has the local symbols R , A , and B . 

When the state indicator is clear, ) SINL returns no result. 

Possible Errors Generated 

2 2 INCORRECT PARAMETER {EXTRANEOUS CHARACTERS AFTER COMMAND) 
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) SIS Displaying the State Indicator and Executing Lines 
Type 

Query System Command 

Form 

)SIS 

Description 

)SIS displays the same information as )SI. In addition, it displays the line 
that is currently being executed and the argument expression of any pendent 
execute functions. 



For example: 




)SI 




F[2] * 




i 




G[302] 




)SIS 




F[2] * BtO 




± F X 




G[3o2] X+Ax2 o Y+± 


■F X 



Here, the function F is suspended at line [2] because of an invalid division 
by zero. The execute function that called F is pending, and its argument is 
displayed. Finally, the function G is pending, and its currently executing line, 
containing the execute function that calls F , is displayed. 

Note that ) SIS does not display the executing line of a locked operation. 

When the state indicator is clear, ) SIS returns no result. 

Possible Errors Generated 



2 2 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 
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) STEP Executing Lines of a Suspended Operation 
Type 

APL Action System Command 

Form 



) STEP In J 

Qualifiers 

/SILENT 

Specifies that APL should not display the operation name and the current line 

that are at the top of the state indicator after the execution of the lines of the 

operation. 

/INTO 

Specifies that you want APL to step into any called operations. 

/OVER 

Specifies that you want APL to step over any called operations. This is the 

default setting. 

Description 

) STEP is a debugging feature that allows you to execute one or more lines of a 
suspended operation. The ) STEP command is valid only when specified from 
immediate mode, and when there is a suspended operation on the top of the 
state indicator. 
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Examples: 



1 FRILL 






[1] 'FRILL . 


tlffF 


1< 


[2] 'FRILL . 


tliVF 


2' 


[3] 'FRILL . 


LJffE 


3 1 


[4] 'FRILL . 


tJM 


4' 


[5] 'FRILL . 


LJffF 


5' 


[6] V 






vr 






[1] FRILL 






[2] <T LINE 


2' 




[3] <T LINE 


3' 




W 'T LINE 


i+' 




[5] 'T LINE 


5' 




[6] V 






1 USTOP 
1 

T 


• 2" 








77 STOPSET 






T[l] FtflU 






)SIS 






T[l] * FRILL 




)STEP <4 


/INTO 


FRILL LINE 1 






FRILL LINE 2 






FRILL LINE 3 






Fi?III[t] 'FKIIZ 


IMS 4 


)SIC 






I 






77 STOPSET 






Till FRILL 






)SIS 






m] * Fi?iu 






)srsp 4 


/OVER 


FBIII IlffF 1 






FRILL LINE 2 






FJ?Iii LIffB 3 






FRILL LINE H 






FRILL LINE 5 






T LINE 2 






T LINE 3 






!T LliVF 4 






T[5] T LI/VF, 5' 
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)SIC 
T 
77 STOPSET 
Till FRILL 

A 

)SIS 
Till * FRILL 

)STEP i+ /OVER/SILENT 
FRILL LINE 1 
FRILL LINE 2 
FRILL LINE 3 
FRILL LINE H 
FRILL LINE 5 
T LINE 2 
T LINE 3 
T LINE H 

)SIS 
T[5] * <T LINE 5' 

Possible Errors Generated 

2 2 INCORRECT PARAMETER {EXTRANEOUS CHARACTERS AFTER COMMAND) 

2 2 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) 

2 2 INCORRECT PARAMETER (PARAMETER OUT OF RANGE) 

46 OPERATION INVALID IN THIS CONTEXT 
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) VARS Displaying a List of Variables 
Type 

Query System Command 

Form 

) VARS \[start-stringfrstop-stringJJ 

Qualifiers 

/ft 'SID: wsname 

Allows you to specify the nonactive workspace APL uses to develop the list. 

/ PASSWORD .pw 

Specifies the password used to save the nonactive workspace. 



Description 



) VARS displays a list of global names used as variable names in a workspace. 
By default, APL displays the list from the currently active workspace. The 
optional / WSID qualifier allows you to specify a nonactive workspace. If the 
nonactive workspace is saved with a password, you must also specify the 
/PASSWORD qualifier. 

The optional string parameters identify starting and stopping points for 
the list. When you specify the string parameters, you can use the * and * 
wildcards. The objects are listed in UAV order, separated by tabs. Each output 
line in the list begins in column 1. 

Note that the wildcard determines the start-string. There is no wildcard for 
the stop-string. 

If you use ) VARS with no parameters, APL displays all the global variable 
names in the workspace: 

)VARS 
A I J K N 

If you include just one argument, APL uses Z as the second string: 

)VARS K 
K S 
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To get a list of all variable names that begin with a given prefix, use the prefix 
for both arguments or use a wildcard: 

)VARS 
PETER STAN STEVE STUART THOMAS WILLIAM 

)VARS ST ST 
STAN STEVE STUART 

)VARS ST* 
STAN STEVE STUART 

Possible Errors Generated 



1 FILE NOT FOUND (FILE NOT FOUND) 

2 2 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 
2 2 INCORRECT PARAMETER (FILE SPECIFICATION IS MISSING) 

2 2 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) 
2 2 INCORRECT PARAMETER (NOT A LETTER) 
5 7 FILE DOES NOT CONTAIN A WORKSPACE 
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) VERSION Displaying the APL Version Number 
Type 

Query System Command 

Form 

) VERSION 

Description 

) VERSION displays the APL version number under which the currently active 
workspace was last saved, followed by a Carriage Return Line Feed, followed 
by the current version of the APL interpreter and a trailing <CRxLF>. 

The display is in the following form: 

Iv.u-edit 

I is the support letter 
v is the version number 
u is the update number 
edit is the edit number 

For example: 

)VERS 
73. 2-83i( 
73.2-831 

Possible Errors Generated 

2 2 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 
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) WIDTH Output Width 
Type 

Query/Change System Command 

Form 

) WIDTH Inl 

Default in Clear Workspace 

System setting 

Description 

) WIDTH displays or changes the setting of the print width system variable 
(D PW) and toggles the video screen between 80- and 132-column mode on 
some terminals (see below). The print width (n in the form) is the number of 
characters that can appear in an output line. The legal values are the integers 
from 35 through 2048. 

The ) WIDTH system command does not affect the allowable length of input 
lines. However, it does affect the display of error messages. Lines in the 
error message that are longer than the print width are truncated; they are 
not wrapped to the next line. If truncating a line would prevent APL from 
displaying the point in the line where the error was discovered, APL cuts part 
of the beginning of the line from the display so that the error is visible. 

Executing the ) WIDTH system command in change mode has the same effect as 
assigning a value to the Q PW system variable (see Chapter 2). 

When you use ) WIDTH to set the print width to above or below 80 on some 
terminals, APL toggles the video screen between 80- and 132-column mode. 
For example, setting the width to 80 or less toggles the screen to 80-column 
mode. Setting the width to 81 or more toggles the screen to 132-column mode. 
The affected terminals are the VT220, VT240, VT320, VT330, VT340, VT102, 
DECTERM, HDSAVT, HDS201, and HDS221. Setting UPW does not cause this 
behavior. 

Note that APL uses two font files for the VT240, VT320, VT330, and VT340 
support: one for 80-column and the other for 132-column mode. If you suspend 
the APL session and change the terminal width at DCL level, the screen will 
be in the new mode and APL will be in the previous mode when you return to 
APL. Use the appropriate value to ) WIDTH to correct it. 
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) WIDTH Output Width 

Examples: 

) WIDTH 
132 

A+<THIS IS A TEST OF THE PRINT WIDTH VARIABLE 1 

A 
THIS IS A TEST OF THE PRINT WIDTH VARIABLE 

) WIDTH 3 5 
WAS 132 

A 
THIS IS A TEST OF THE PRINT WIDTH V 
ARIABLE 

Possible Errors Generated 



22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 
2 2 INCORRECT PARAMETER (ILL FORMED NUMERIC CONSTANT) 
2 2 INCORRECT PARAMETER (PARAMETER OUT OF RANGE) 
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) WSID Workspace Identification 
Type 

Query/Change System Command 

Form 

)WSID RwsnameU 

Default in Clear Workspace 

CLEAR WS with a blank password 

Qualifiers 

/PASSWORD I :IpivDl 

Specifies the password associated with the workspace. 



Description 



) WSID displays or changes the name of the active workspace. When you use 
) WSID to change the name of the active workspace, you must specify the 
wsname parameter. 

You can use the password qualifier of ) WSID to change the password associated 
with a workspace. When you use ) WSID as an action command, the password 
is changed (but not displayed) either to the password you specify as the 
argument to /PASSWORD or, if you do not specify a password, to the empty 
password (eight blanks). The password is never changed when you use ) WSID 
as a query command ()WSID with no argument). For example: 

} WSID MYWS/ PASSWORD : SESAME 
WAS EXAMPLE 

)WSID 
MWS 

) PASSWORD 
/PASSWORD-.SESAME 

)WSID YOURWS 
WAS MYWS 

) PASSWORD 
/PASSWORD: 
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The file specification you give for wsname must include at least a file name. 
APL assumes default values for the rest of the specification; that is, it assumes 
the file type .APL, the current user device and directory, and an empty 
password. 

For more information on QLZ, see Chapter 2. 

Possible Errors Generated 



2 2 INCORRECT PARAMETER 

22 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) 
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If an error is detected during the evaluation of an expression, APL displays the 
following: 

• An appropriate primary error message from the list included in this 
appendix 

• The text of the line in which the error occurred 

• A caret (a ) approximately underneath the point in the line at which the 
error was discovered 

Often the primary error message is followed on the same line by a secondary 
error message that offers a more specific explanation of what caused the error. 
Secondary error messages are surrounded by parentheses. (If you do not want 
to see secondary error messages, set □ TERSE to 1.) 

When an expression that produces an error is executed by the □ XQ function, 
the result returned is an empty array with the shape n, where n is an ERROR 
NUMBER. For example, the APL error number for VALUE ERROR is 11, so when 
an expression that produces a VALUE ERROR is executed by the DXQ function, 
the value returned is an empty array with the shape 11: 

OQXQ 'A+B< 
PC 
11 

UERROR 
11 UXQ VALUE ERROR 
A+B 

A 

The following pages list the primary error messages and, when appropriate, 
explain what they mean and what you can do to correct the errors. Some of the 
secondary error messages that APL may display with the primary messages 
are also identified. In many cases, no explanation of secondary error messages 
is given, because the message is self-explanatory. 
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1 FILE NOT FOUND 

Explanation: The requested workspace or file was not found in the 
specified disk area. 

1 FILE NOT FOUND ( FILE NOT FOUND) 

2 SYSTEM ERROR 

Explanation: An internal inconsistency was detected. Please report this 
error to your Digital software specialist. 

3 WORKSPACE FULL 

Explanation: The active workspace could not retain all the information 
requested, nor could it expand further. Erase unneeded objects, issue a 
) MAXCORE command to enlarge the workspace, or do a ) SAVE, ) CLEAR, 
and ) COPY sequence on the needed information. 

3 WORKSPACE FULL ( EXCESSIVE FRAGMENTATION) 

3 WORKSPACE FULL ( MAXCORE EXCEEDED) 

3 WORKSPACE FULL ( VIRTUAL MEMORY EXHAUSTED) 

4 NOT A VALID SYSTEM IDENTIFIER 

Explanation: An attempt was made to use a system identifier that is not 
supported by this APL implementation. 

5 DEFN ERROR 

Explanation: Invalid syntax was detected in a line or command entered 
in function-definition mode. 

5 DEFN ERROR ( CANNOT DELETE HEADER) 

5 DEFN ERROR ( EDIT COMMAND ILLEGAL IN QUAD FX ARGUMENT) 

5 DEFN ERROR ( EXPECTING A DOLLAR SIGN) 

5 DEFN ERROR ( EXPECTING A NUMBER) 

5 DEFN ERROR ( EXPECTING A NUMBER, OR RIGHT BRACKET) 

5 DEFN ERROR ( EXPECTING A NUMBER, QUAD, DELTA, OR JOT) 

5 DEFN ERROR ( EXPECTING A QUAD, OR RIGHT BRACKET) 
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5 DEFN ERROR ( EXPECTING A QUAD) 

5 DEFN ERROR ( EXPECTING A RIGHT BRACKET) 

Explanation: An error was discovered while the function editor scanned 
an edit command string. 

5 DEFN ERROR ( EXPECTING A STRING DELIMITER) 

Explanation: Did not find a delimiter for one of the search or replace 
strings for dollar sign editing. 

5 DEFN ERROR ( ILL FORMED LINE NUMBER) 

5 DEFN ERROR ( ILL FORMED NUMERIC CONSTANT) 

5 DEFN ERROR ( LEFT BRACKET EXPECTED) 

5 DEFN ERROR ( LINE NUMBER OUT OF RANGE) 

Explanation: A line number greater than 9,999 was specified. 

5 DEFN ERROR ( LINE NUMBER TRUNCATED) 

Explanation: More than five decimal digits were specified in a line 
number. 

5 DEFN ERROR ( LOCAL SYMBOL EXPECTED) 

5 DEFN ERROR ( NAME IN USE) 

Explanation: An attempt was made to use the same identifier for both 
arguments of an operation, or for both a label and a local symbol or 
argument. 

5 DEFN ERROR ( NEGATIVE INTEGER NOT ALLOWED) 

5 DEFN ERROR ( NO PREVIOUS SEARCH STRING) 

Explanation: The search string is empty and there was no previous use 
of dollar sign editing during this activation of the Del editor. 

5 DEFN ERROR ( NO SYMBOL AFTER OPENING DEL) 

Explanation: The operation name was missing from the line entered. 

5 DEFN ERROR ( NO SYMBOL AFTER RESULT ARROW) 

5 DEFN ERROR ( NOT A SYSTEM VARIABLE) 

Explanation: An attempt was made to localize a system function. 
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5 DEFN ERROR ( NOT AN INTEGER) 

Explanation: A print position parameter that is not an integer was 
entered in superedit mode. 

5 DEFN ERROR ( NOT IN FUNCTION DEFINITION MODE) 

Explanation: An edit command was entered outside of function-definition 
mode. Edit commands are illegal in immediate mode except when used to 
display or edit the last executed input line. 

5 DEFN ERROR ( OPERATION LOCKED) 

Explanation: An attempt was made to list or change a locked operation. 

5 DEFN ERROR ( OPERATION SUSPENDED, PENDENT, OR MONITORED) 

Explanation: An attempt was made to edit a pendent or monitored 
operation, or an attempt was made to change the number of lines in a 
suspended operation or the definition of a local symbol in a suspended 
operation. 

5 DEFN ERROR ( OPERATION SUSPENDED OR PENDENT) 

Explanation: For ) EDIT, an attempt was made to end the VAXTPU 
session with an EXIT command when you are not allowed to modify the 
function. 

5 DEFN ERROR ( RIGHT BRACE EXPECTED) 

Explanation: An error was discovered while the function editor scanned 
an operation header and found a left brace that was not balanced with a 
right brace. 

5 DEFN ERROR ( RIGHT PARENTHESIS EXPECTED) 

5 DEFN ERROR ( RIGHT PARENTHESIS OR SYMBOL EXPECTED) 

5 DEFN ERROR ( SEMICOLON EXPECTED) 

5 DEFN ERROR ( SYMBOL EXPECTED) 

5 DEFN ERROR ( TOO MANY LINES IN OPERATION) 

Explanation: An attempt was made to close an operation that has more 
than 10,000 lines. 

5 DEFN ERROR ( UNEXPECTED CHARACTER IN HEADER) 
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6 LABEL ERROR 

Explanation: Improper use of a colon was detected, or an improper 
variable name was entered as a label. 

6 LABEL ERROR ( DUPLICATE LABEL) 

6 LABEL ERROR ( NAME IN USE) 

Explanation: An attempt was made to use the same identifier for both a 
label and a local symbol or argument. 

6 LABEL ERROR ( OPERATION SUSPENDED , PENDENT, OR MONITORED) 

Explanation: An attempt was made to change a label definition in a 
suspended, pendent, or monitored operation. 

7 SYNTAX ERROR 

Explanation: Invalid syntax was detected, such as an operation call with 
missing arguments, or an unmatched parenthesis. 

7 SYNTAX ERROR ( ILL FORMED NUMERIC CONSTANT) 

7 SYNTAX ERROR ( MISMATCHED DELIMITERS) 

7 SYNTAX ERROR ( MISSING ARGUMENT) 

7 SYNTAX ERROR ( MISSING LEFT ARGUMENT TO ASSIGNMENT) 

Explanation: There is no left argument to the specification function (+- ). 
For example: ^2 is incorrect. 

7 SYNTAX ERROR (MISSING OPERAND) 

7 SYNTAX ERROR ( NO DYADIC FORM OF FUNCTION) 

7 SYNTAX ERROR ( NO MONADIC FORM OF FUNCTION) 

Explanation: Inner product and outer product are dyadic. 

7 SYNTAX ERROR ( OPERATOR HAS NO OPERANDS) 

7 SYNTAX ERROR ( UNBALANCED DELIMITER) 

7 SYNTAX ERROR ( BRANCH NOT ALLOWED IN MIDDLE OF AN EXPRESSION) 
Explanation: The branch O ) function was used when it was not the 
principal function of a statement. 
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7 SYNTAX ERROR ( DEPTH ERROR) 

Explanation: Either there are too many nested parentheses or brackets, 
or the expression is too complex for APL to parse. 

7 SYNTAX ERROR ( ILLEGAL CHARACTER IN EXPRESSION) 

Explanation: An internal Q A V code appeared outside of a literal or 
comment. 

7 SYNTAX ERROR ( NO DYADIC FORM OF DERIVED FUNCTION) 

Explanation: Scan, reduction, expansion, compression, and replication all 
derive monadic functions. 

7 SYNTAX ERROR ( NO MONADIC FORM OF DERIVED FUNCTION) 

Explanation: Inner and outer product both derive dyadic functions. 

7 SYNTAX ERROR ( NON-NILADIC FUNCTION HAS NO ARGUMENTS) 

Explanation: An ambivalent, dyadic, or monadic user-defined operation 
was invoked without any arguments. 

7 SYNTAX ERROR ( NOT IN FUNCTION DEFINITION MODE) 

Explanation: An editing command was entered at the beginning of a line 
in immediate mode. 

7 SYNTAX ERROR ( SUBSCRIPT NOT ALLOWED) 

Explanation: An attempt was made to index something that does not 
have a value. 

7 SYNTAX ERROR ( WRONG NUMBER OF ARGUMENTS TO USER FUNCTION) 

Explanation: A monadic user-defined operation was invoked with two 
arguments. 

8 ERROR RETURNING FROM EXTERNAL ROUTINE 

8 ERROR RETURNING FROM EXTERNAL ROUTINE ( DOMAIN ERROR) 

Explanation: A conversion failed when data returned to the workspace. 

8 ERROR RETURNING FROM EXTERNAL ROUTINE ( ILLEGAL ASCII CHARACTER) 

Explanation: A conversion to ASCII failed as character data returned to 
the workspace. 
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8 ERROR RETURNING FROM EXTERNAL ROUTINE ( LENGTH ERROR) 

Explanation: A Varying string (/ TYPE : VT) returned to the WS is bigger 
than it was when it was passed to the external routine. (It is allowed to be 
smaller or the same size.) 

9 RANK ERROR 

Explanation: The ranks of two operands did not conform. 

9 RANK ERROR ( ITEMS NOT SCALAR OR ALL THE SAME RANK) 

Explanation: The items of the right argument of disclose (=> ) are neither 
scalars nor of matching rank. 

9 RANK ERROR ( ITEMS NOT SINGLETON OR ALL THE SAME RANK) 

Explanation: The items of B must be either singletons or of matching 
rank. 

9 RANK ERROR ( LEFT ITEM NOT VECTOR DOMAIN) 

Explanation: Either the left argument or an item in the left argument to 
pick (=> ) is not a singleton and its rank is greater than 1. 

9 RANK ERROR ( MUST BE VECTOR) 

Explanation: The value and each item in the value, must be vectors. 

9 RANK ERROR ( NOT A SCALAR, VECTOR, OR MATRIX) 

Explanation: The rank of an argument to fB , V or ^ is greater than 2. 

9 RANK ERROR ( NOT MATRIX DOMAIN) 

9 RANK ERROR ( NOT SINGLETON) 

Explanation: Deal, and the QWAIT and DDL functions accept only single 
numbers as an argument. 

9 RANK ERROR ( NOT VECTOR DOMAIN) 

Explanation: An argument or value is not a singleton and its rank is 
greater than 1. 

9 RANK ERROR ( NUMERIC PRIMARY KEY MUST BE SINGLETON) 

Explanation: A numeric key for a keyed file must be a singleton. 

9 RANK ERROR ( RANKS DIFFER BY MORE THAN ONE) 

Explanation: The arguments, after singleton extension to catenate or 
rotate differ in rank by more than one. 
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10 LENGTH ERROR 

Explanation: The shapes of two operands did not conform. 

10 LENGTH ERROR ( ARGUMENT MUST BE 1 OR 2 ELEMENTS) 

Explanation: , a , D CIQ, and D COQ may have at most two items in their 
right argument. 

10 LENGTH ERROR ( ARGUMENT STRING IS TOO LONG) 

Explanation: The left argument to dyadic 4 or f is greater than 256 
characters along any one axis. 

10 LENGTH ERROR ( DATA TYPE EXCEEDS DATA LENGTH) 

Explanation: The data type specified for B file input or the Q CIQ function 
is incompatible with the length of the left argument. 

10 LENGTH ERROR ( DATA TYPE MISSING) 

Explanation: The data type parameter in the right argument to D CIQ is 
required in this case. 

10 LENGTH ERROR ( DISPLAY CONTROL ITEM WRONG LENGTH) 

Explanation: The first item must have length 4. The second item can 
either be empty or have length 8. 

10 LENGTH ERROR ( DISPLAY CONTROL VECTOR MUST BE TWO ITEMS) 
Explanation: The value must have length 2. 

10 LENGTH ERROR ( ILLEGAL EMPTY ARGUMENT) 

Explanation: An empty argument was used with QFMT, UMAP, 0QCO, 
UQLD, DQPC, or D SIGNAL. 

10 LENGTH ERROR ( INDEX LESS THAN INDEX ORIGIN) 

Explanation: An index is less than the current setting of D 10. 

10 LENGTH ERROR ( INDEX OUT OF RANGE) 

Explanation: For pick (=> ), an element of the left argument exceeds the 
length of the corresponding axis of an item of the right argument. 

10 LENGTH ERROR ( ITEM COUNT MISMATCH) 

Explanation: If the number of variable names specified in the right 
argument to UPACK, is not equal to the number of packets contained in the 
left argument. 
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10 LENGTH ERROR ( KEY VALUE TOO LARGE FOR KEY SIZE) 
Explanation: For IKY files. 

10 LENGTH ERROR ( LEFT ARGUMENT LENGTH GREATER THAN RIGHT ARGUMENT 
DEPTH) 

Explanation: For pick (=> ), the length of the left argument is greater than 
the depth of the right argument. 

10 LENGTH ERROR ( LEFT ITEM LENGTH NOT EQUAL TO SELECTED ITEM RANK) 

Explanation: For pick (=■ ), the length of an item of the left argument does 
not match the rank of the selected item at the corresponding depth of the 
right argument. 

10 LENGTH ERROR ( LEFT LENGTH NOT EQUAL TO RIGHT RANK) 

Explanation: For + , + , or dyadic is; , where no axis has been specified and 
the right argument B is not a scalar and its rank is not equal to the length 
of the left argument A . 

10 LENGTH ERROR ( LENGTHS OF INNER AXES DO NOT MATCH) 

Explanation: For Base, the length of the last axis of the left argument 
A is not equal to the length of the first axis of the right argument B , and 
neither axis is 1. For Inner product, after singleton extension, the left 
argument last axis length must equal the right argument first axis length. 

10 LENGTH ERROR ( NOT SINGLETON) 

Explanation: The value is not a single item. Dyadic (for I AS files), ?, 
and the numeric system variables require a single item for their argument 
or value. For example, the following is incorrect: Q 10*- 1 3 

10 LENGTH ERROR ( NUMBER OF ROWS MUST MATCH) 

Explanation: The number of rows in the arguments to dyadic EB must 
match. 

10 LENGTH ERROR ( SHAPES OFF AXIS DO NOT MATCH) 

Explanation: For Catenate and Rotate, after singleton extension, the 
shape of the left argument must match the shape of the right argument 
except along the specified axis. 

10 LENGTH ERROR ( THERE ARE FEWER ROWS THAN COLUMNS) 

Explanation: The number of rows in the right argument to @ must be 
greater than or equal to the number of columns. 
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10 LENGTH ERROR ( TOO MANY ELEMENTS IN KEY SPECIFICATION) 

Explanation: An attempt was made to include elements other than 
value, key-num, tech, and key-type between the brackets of your file output 
expression. 

11 VALUE ERROR 

Explanation: A variable name was used and has not been assigned a 
value, or a user-defined operation that should return a value was executed 
and it did not return a value. 

11 VALUE ERROR ( BRANCH HAS NO RESULT) 

Explanation: A branch O ) expression was used as a response to input. 

11 VALUE ERROR ( FUNCTION DOES NOT RETURN A RESULT) 

11 VALUE ERROR ( FUNCTION RESULT UNDEFINED) 

11 VALUE ERROR ( NO VALUE TO ASSIGN) 

Explanation: There is no right argument to the specification function O). 
For example: T+- is incorrect. 

11 VALUE ERROR (REQUIRED VALUE NOT SUPPLIED) 

11 VALUE ERROR ( SUBSCRIPTED NAME IS UNDEFINED) 

Explanation: In the form A [in *-B, A is not a defined name. 

1 H DEPTH ERROR 

Explanation: For Q FMT there are more than eight nested parentheses in 

A. 

14 DEPTH ERROR ( LEFT ARGUMENT DEPTH GREATER THAN 2 ) 

Explanation: The items in A must be simple (vectors or singletons). 

14 DEPTH ERROR ( TOO MANY DIVERTED INPUTS) 

Explanation: Files were nested to a depth greater than 10 with ) INPUT. 

15 DOMAIN ERROR 

Explanation: The values given for the arguments were outside of the 
function domain. For Q 0M, the argument is not Boolean and is nonempty. 

15 DOMAIN ERROR ( BUFFER OVERFLOW) 
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15 DOMAIN ERROR ( CANNOT MODIFY SELECTIVE ASSIGNMENT TARGET) 

Explanation: The variable being assigned to cannot be modified by the 
expression forming the left argument of the selective assignment. For 
example: ( ( p A+-\ 2) <$>A) + ' AB' is incorrect. 

15 DOMAIN ERROR ( CANNOT SIGNAL EOF) 

Explanation: An attempt was made to use 75 as the right argument to 

U SIGNAL. SIGNAL does not accept 75 as a right argument. 

15 DOMAIN ERROR ( CHANNEL NOT ASSIGNED) 

Explanation: The value in the right argument does not refer to an 
assigned channel. An attempt was made to use U WAIT or Q REWIND on an 
unassigned channel. 

15 DOMAIN ERROR ( CHANNEL NOT ASSIGNED TO A KEYED FILE) 

Explanation: The file associated with the channel number is not a IKY 
file. 

15 DOMAIN ERROR ( CHARACTER KEY TOO LONG OR NOT IN VECTOR DOMAIN) 
Explanation: For IKY files. 

15 DOMAIN ERROR ( CONFLICTING QUALIFIERS SPECIFIED) 

Explanation: More than one of the following qualifiers was specified in 
the argument to BASS: /READONLY, /WRITEONLY, or /UPDATE. 

15 DOMAIN ERROR ( DATA TYPE MUST BE UNSPECIFIED OR ZERO) 
Explanation: For □ CI Q. 

15 DOMAIN ERROR ( DELETION NOT ALLOWED) 

Explanation: A sequential delete was attempted for a IKY or I AS file. 

15 DOMAIN ERROR ( DIVISION BY ZERO) 

Explanation: Division by zero is attempted. 

15 DOMAIN ERROR ( DUPLICATE FMT QUALIFIER) 

Explanation: A qualifier is used more than once with a particular format 
phrase. 

15 DOMAIN ERROR ( DUPLICATE FMT STANDARD SUBSTITUTION CHARACTER) 
Explanation: A substitute for a standard symbol character was specified 
more than once. 
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15 DOMAIN ERROR ( EMPTY FMT STRING PARAMETER NOT ALLOWED) 
Explanation: The O, R, or S qualifier string is empty. 

15 DOMAIN ERROR ( ENCLOSED/ HETEROGENEOUS ARRAY NOT ALLOWED) 

Explanation: The argument is not a simple, homogeneous array. For 
QDC, the first item must be a simple homogeneous array. The second item, 
if not empty, must be simple. 

15 DOMAIN ERROR ( ENCLOSED VALUE REQUIRED) 

Explanation: The value must be an enclosed array. 

15 DOMAIN ERROR ( ERROR ACTIVATING IMAGE) 

Explanation: For DAMP, the shared image named by B does not exist. 
For □ TT, ) EDIT, or the initialization stream, there is an attempt to 
enter VT220, VT240, VT320, VT330, VT340 or DECterm mode when 
SYS$SYSTEM:APLSHR is not accessible. APL can signal this error when 
you invoke APL with the /TERMINAL qualifier, when you use ) EDIT with 
the /TERMINAL qualifier, when you use ) EDIT with an HDS201 or HDS221 
terminal, or when you set Q TT. 

15 DOMAIN ERROR ( ERROR PARSING ARGUMENT TO BLOCK SIZE) 

Explanation: An error was discovered when parsing the /BLOCKSIZE 
qualifier in the argument to DA 55. 

15 DOMAIN ERROR ( ERROR PARSING ARGUMENT TO BUFFER COUNT) 

Explanation: An error was discovered when parsing the /BUFFERCOUNT 
qualifier in the argument to QASS. 

15 DOMAIN ERROR ( ERROR PARSING ARGUMENT TO CCONTROL) 

Explanation: An invalid value was specified for the / CCONTROL qualifier 
in the argument to BASS. 

15 DOMAIN ERROR ( ERROR PARSING ARGUMENT TO DEFAULT FILE SPEC) 

Explanation: An error was discovered when parsing the /DEFAULTFILE 
qualifier in the argument to DA 55. 

15 DOMAIN ERROR ( ERROR PARSING ARGUMENT TO DISPOSE) 

Explanation: An error was discovered when parsing the /DISPOSE 
qualifier in the argument to DA 55. 
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15 DOMAIN ERROR ( ERROR PARSING ARGUMENT TO EVENT FLAG) 

Explanation: An error was discovered when parsing the /EFN qualifier in 

the argument to OASS. 

15 DOMAIN ERROR ( ERROR PARSING ARGUMENT TO KEY SPECIFICATION) 
Explanation: An error was discovered when parsing the /KY qualifier in 
the argument to OASS. 

15 DOMAIN ERROR ( ERROR PARSING ARGUMENT TO MAXLEN) 

Explanation: An error was discovered when parsing the /MAXLEN 
qualifier in the argument to UASS. 

15 DOMAIN ERROR ( ERROR PARSING ARGUMENT TO PROTECTION) 

Explanation: An error was discovered when parsing the /PROTECTION 
qualifier in the argument to D^SS. 

15 DOMAIN ERROR ( ERROR PARSING ARGUMENT TO RECORD TYPE) 

Explanation: An error was discovered when parsing the /RECORDTYPE 
qualifier in the argument to QASS. 

15 DOMAIN ERROR ( EXTRANEOUS CHARACTERS AFTER COMMAND) 

Explanation: There are characters other than spaces following the 
command. 

15 DOMAIN ERROR ( FILE IS ASSIGNED WRITE ONLY) 

Explanation: The file associated with the channel number cannot be 
rewound because it was assigned with the /WRITEONLY qualifier. 

15 DOMAIN ERROR ( FILE SPECIFICATION IS MISSING) 

Explanation: There is no file specification or default file specification in 
the argument to UA SS. 

15 DOMAIN ERROR ( FMT DECORATION OR LITERAL STRING TOO LONG) 

Explanation: A text string in the left argument consists of more than 255 
characters. 

15 DOMAIN ERROR ( FMT RIGHT ARGUMENT DOES NOT MATCH FORMAT PHRASE) 
Explanation: The data type of a value in the right argument does not 
match the type called for by a format phrase specification in the left 
argument. 
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15 DOMAIN ERROR ( FONT FILE COULD NOT BE OPENED) 

Explanation: For Q TT or the initialization stream, there is an attempt to 
enter VT220, VT240, VT320, VT330 or VT340 mode when the APL font 
file is not accessible. Possibly, the file does not exist or is associated with a 
protection code that does not allow access. 

15 DOMAIN ERROR ( FUNCTION HAS NO FILL ITEM) 

Explanation: Either each (" ) or outer product (° ./) was applied with a 
user-defined function to an empty argument. 

15 DOMAIN ERROR ( FUNCTION HAS NO IDENTITY ELEMENT) 

Explanation: The inner axes of an inner product or the reduction axis is 
empty and there is no identity element for the left operand function. 

15 DOMAIN ERROR ( FUNCTION MISSING) 

Explanation: For UMAP, if function-name is not present or if it is followed 
by any attributes. 

15 DOMAIN ERROR ( ILL FORMED FMT PARAMETER) 

Explanation: An invalid numeric parameter (such as a negative sign with 
no number) was found. 

15 DOMAIN ERROR ( ILL FORMED NAME) 

Explanation: For QMAP, if the left argument has a formal parameter that 
contains illegal characters, or if the right argument has a value for the 
/ENTRY or / VALUE qualifier that contains illegal characters. 

15 DOMAIN ERROR ( ILLEGAL ASCII CHARACTER) 

15 DOMAIN ERROR ( ILLEGAL CHARACTER IN FMT LEFT ARGUMENT) 

Explanation: An invalid character appears in the left argument of D FMT. 

15 DOMAIN ERROR ( ILLEGAL COMPOSITE CHARACTER) 

15 DOMAIN ERROR ( ILLEGAL DATA TYPE CONVERSION) 

15 DOMAIN ERROR ( ILLEGAL DEC MULTINATIONAL CHARACTER) 

15 DOMAIN ERROR ( ILLEGAL EMPTY ARGUMENT) 

15 DOMAIN ERROR ( ILLEGAL FMT FORMAT PHRASE) 

Explanation: A letter in the left argument of Q FMT does not represent a 
valid format phrase or qualifier. 
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15 DOMAIN ERROR ( ILLEGAL FMT G FORMAT PHRASE PATTERN CHARACTER) 

Explanation: An invalid character was found in a type G format phrase 
pattern string. 

15 DOMAIN ERROR ( ILLEGAL FMT LITERAL STRING DELIMITER) 
Explanation: A decorator or literal string delimiter was invalid. 

15 DOMAIN ERROR ( ILLEGAL FMT S QUALIFIER SYMBOL) 

Explanation: The first symbol of a substitution pair is not * , . , ,,0,9, 
Z , or @ . 

15 DOMAIN ERROR ( ILLEGAL ISO 8BIT CHARACTER) 

15 DOMAIN ERROR ( ILLEGAL LEFT ARGUMENT TO ASSIGNMENT) 

Explanation: An element of A is not an undefined or variable name. 

15 DOMAIN ERROR ( ILLEGAL MODE) 

15 DOMAIN ERROR ( ILLEGAL NAME CLASS) 

Explanation: For QPACK, the right argument is not a variable. For 
assignment («- ), the left argument is neither a variable nor an undefined 
name. 

15 DOMAIN ERROR ( ILLEGAL SELECTIVE ASSIGNMENT FUNCTION) 

Explanation: The function f is not one of the allowed selection functions. 

15 DOMAIN ERROR ( ILLEGAL USE OF FMT QUALIFIER) 

Explanation: The specified qualifier and format phrase are incompatible. 

15 DOMAIN ERROR ( INCORRECT PARAMETER) 

Explanation: A parameter in the left argument to Q MAP is incorrect. 

15 DOMAIN ERROR ( INCORRECT TYPE) 

Explanation: An argument is non-empty and is either numeric, when it 
should be character, or character when it should be numeric. For example, 
the following is incorrect: D l0-<- ' G ' 

15 DOMAIN ERROR ( INDEX LESS THAN INDEX ORIGIN) 

Explanation: An element of an argument is less than the current setting 
of D 10. 
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15 DOMAIN ERROR ( INDEX OUT OF RANGE) 

Explanation: An element of the left argument exceeds the length of the 
corresponding axis of an item of the right argument. 

15 DOMAIN ERROR ( INTEGER OVERFLOW) 

15 DOMAIN ERROR ( INVALID CHANNEL NUMBER) 

Explanation: A channel number is not between ~ 999 and 999 or is 0. 

15 DOMAIN ERROR ( INVALID CIQ HEADER) 

15 DOMAIN ERROR ( INVALID EXTERNAL DATA TYPE) 

15 DOMAIN ERROR ( INVALID FILE SPECIFICATION) 

Explanation: There is an error in the shared image file specification in 
the right argument of OMA P. 

15 DOMAIN ERROR ( INVALID FUNCTION IN SELECTIVE ASSIGNMENT) 

Explanation: The principal function or functions in the left argument 
is ineligible for use with selective assignment. For example: ( A+B) -<-3 is 
incorrect. 

15 DOMAIN ERROR ( INVALID HEADER TYPE) 

Explanation: An incorrect header type was specified for QCOQ or Q CIQ. 

15 DOMAIN ERROR ( INVALID KEYED FILE PURE DATA TYPE) 
Explanation: For IKY files. 

15 DOMAIN ERROR ( INVALID LENGTH IN PACK HEADER) 

Explanation: The first item of the value in the left argument to D PA CK 
must equal the length of the left argument. 

15 DOMAIN ERROR ( INVALID OBJECT IN INDEXED ASSIGNMENT) 

15 DOMAIN ERROR { INVALID OBJECT IN SELECTIVE ASSIGNMENT) 

Explanation: The first object inside the parentheses of selective 
assignment must be a variable name. For example: ( 1+ 2 ) -=-3 is incorrect. 

15 DOMAIN ERROR ( INVALID OBJECT IN STRAND ASSIGNMENT) 
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15 DOMAIN ERROR ( INVALID PACK HEADER) 

Explanation: The length of the left argument to QPACK must be greater 
than or equal to 8. The shortest possible packed data has four elements for 
the QPACK header and 4 elements for the shortest Q COQ header. 

15 DOMAIN ERROR ( INVALID RANK IN PACK HEADER) 

Explanation: The value of the third element in the left argument to 
D PACK must equal 1 (1 means the packed data is a vector). 

15 DOMAIN ERROR ( INVALID RHO VECTOR IN PACK HEADER) 

Explanation: The length of the left argument to D PA CK must equal the 
value of the fourth element in the left argument plus 4. 

15 DOMAIN ERROR ( INVALID TYPE IN PACK HEADER) 

Explanation: The value of the second element in the left argument to 
QPACK must equal 1 (1 means the type is integer). 

15 DOMAIN ERROR ( INVALID WATCH MODE) 

Explanation: An incorrect mode was specified for D NATCH. 

15 DOMAIN ERROR ( KEY OF REFERENCE OUT OF RANGE OR NOT A NUMERIC 
SINGLETON) 

Explanation: An attempt was made to specify a key of reference that 
is not a numeric singleton or that is less than or greater than 254 
(inclusive). 

15 DOMAIN ERROR ( KEY NOT FOUND IN TREE) 

Explanation: For QMAP, if the left argument specifies an entry point that 
does not exist in the shared image. 

15 DOMAIN ERROR ( LEFT ARGUMENT NOT DENSE FROM INDEX ORIGIN) 

Explanation: For dyadic isj , the left argument is not a dense sequence 
beginning at Q 10. 

15 DOMAIN ERROR ( MISSING FMT FORMAT PHRASE SEPARATOR) 

Explanation: A format phrase separator (such as a comma or parenthesis) 
was expected but not supplied. 

15 DOMAIN ERROR ( MISSING FMT FORMAT PHRASE /QUALIFIER CHARACTER) 
Explanation: A format phrase or qualifier was expected but not supplied. 
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15 DOMAIN ERROR ( MISSING FMT FORMAT PHRASE I QUALIFIER PARAMETER) 

Explanation: No string was included with a decorator or an S format 
phrase; no number was included where a width or decimal parameter was 
required; or no number was included with a K or W qualifier. 

15 DOMAIN ERROR ( MISSING LITERAL STRING IN FMT LEFT ARGUMENT) 
Explanation: The text string parameter was missing from a decorator. 

15 DOMAIN ERROR ( NAME IN USE) 

Explanation: For UMAP, if the name specified for function-name is already 
defined as an object other than a function. 

15 DOMAIN ERROR ( NEGATIVE INTEGER NOT ALLOWED) 

15 DOMAIN ERROR ( NEGATIVE NUMBER NOT ALLOWED) 

Explanation: The value of the argument is less than 0. 

15 DOMAIN ERROR ( NO DIGIT SELECTOR IN FMT G FORMAT PHRASE PATTERN) 

Explanation: A type G format phrase pattern does not contain at least 
one 9 or one Z, or a character that is substituted for a 9 or a Z. 

15 DOMAIN ERROR ( NO FMT EDITING FORMAT PHRASE) 

Explanation: The left argument of □ FMT does not contain at least one 
value editing format phrase, that is, at least one of type A, I, E, F, G, or Y. 

15 DOMAIN ERROR {NOT A LETTER) 

Explanation: A nonletter was used as the left argument to QNL. 

15 DOMAIN ERROR ( NOT A SYSTEM VARIABLE) 

Explanation: The argument is a quad name but not a system variable. 

15 DOMAIN ERROR ( NOT A VALID SYSTEM IDENTIFIER) 

15 DOMAIN ERROR ( NOT AN EXTERNAL FUNCTION) 

Explanation: For UMAP, if the argument names an illegal identifier, a 
system identifier, a name with no value, or a name that is not an external 
function. 

15 DOMAIN ERROR ( NOT AN INTEGER) 

Explanation: An argument is not a near-integer. For example, the 
following is incorrect: Q 10*- 2 . 5 
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15 DOMAIN ERROR ( OPERATION SUSPENDED, PENDENT, OR MONITORED) 

15 DOMAIN ERROR ( PARAMETER OUT OF RANGE) 

Explanation: An attempt was made to use an unavailable value as the 
argument. For QDC, Elements 1 and 2 of the first item can only be ~ 1,0, 
or 1. For DFMT, the repetition count, field width, number of decimal places 
or significant digits, column position, scale factor, or exponent size is out of 
range. 

15 DOMAIN ERROR ( REDUNDANT KEYWORD OR QUALIFIER) 

Explanation: A keyword or qualifier was repeated in the argument to 

OASS. 

15 DOMAIN ERROR ( RIGHT ARGUMENT IS LESS THAN LEFT) 
Explanation: For dyadic ? . 

15 DOMAIN ERROR ( RIGHT ARG TOO DEEPLY NESTED) 

Explanation: The right argument to D FMT is not a vector domain of 
simple arrays. 

15 DOMAIN ERROR ( SEMICOLON LIST NOT ALLOWED) 

Explanation: A semicolon list was used as an argument to a primitive 
function. 

15 DOMAIN ERROR ( SINGULAR MATRIX) 

Explanation: For g , division by is attempted. 

15 DOMAIN ERROR ( SYSTEM VARIABLE MUST BE OR 1 OR 2 OR 3) 
Explanation: The value of Q GAG must be 0, 1, 2, or 3. 

15 DOMAIN ERROR ( SYSTEM VARIABLE VALUE MAY ONLY BE OR 1) 

Explanation: 010, UNG, UTERSE, QTIMEOUT, or UTLE accept only or 1. 

15 DOMAIN ERROR ( TIMEOUT READ UNSUPPORTED FOR CURRENT VALUE OF 
QUAD TT) 

Explanation: An attempt was made to set □ TIME LIMIT while the current 
value of D TT indicates a VT220, VT240, VT320, VT330, VT340 or DECterm 
terminal. 

15 DOMAIN ERROR ( UNBALANCED PARENS IN FMT LEFT ARGUMENT) 

Explanation: The parentheses in the left argument of D FMT are not 
nested properly. 
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15 DOMAIN ERROR ( UNBALANCED TEXT DELIMITER IN FMT LEFT ARGUMENT) 

Explanation: The closing delimiter for a text string was not compatible 
with the opening delimiter. 

15 DOMAIN ERROR ( UNPAIRED SYMBOL IN FMT S QUALIFIER) 

Explanation: The length of the standard symbol substitution string is not 
even. 

15 DOMAIN ERROR ( UNRECOGNIZED SEARCH MODE) 
Explanation: For IKY files. 

15 DOMAIN ERROR ( UNSUCCESSFUL TRAP IN LOCKED FUNCTION) 

Explanation: An error occurred while executing the trap expression in a 
locked function. 

15 DOMAIN ERROR ( WIDTH TOO SMALL) 

Explanation: The width parameter for dyadic ▼ is too small to 
accommodate the data. 

15 DOMAIN ERROR ( WILDCARDS NOT ALLOWED IN FILE SPECIFICATION) 

Explanation: Wildcards are not allowed in the right argument to UMAP. 

16 UNBALANCED DELIMITER 

Explanation: An input line has unbalanced parentheses, or the argument 
to the execute function contains unbalanced quotation marks or A 
characters. 

17 EDIT ERROR 

Explanation: An improper character editing request was entered. 

17 EDIT ERROR ( COLUMN POSITION OUT OF RANGE) 

Explanation: The print position number that was entered for superedit 
was greater than the page width, or was negative. 

17 EDIT ERROR ( EXPECTING A RIGHT BRACKET) 

Explanation: An attempt was made to delete the line number during line 
editing. 

17 EDIT ERROR ( ILL FORMED LINE NUMBER) 
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17 EDIT ERROR ( ILLEGAL CHARACTER IN LINE EDIT COMMAND) 

Explanation: The command that was entered included a character other 
than a letter, digit, /, space, or backspace. 

17 EDIT ERROR ( LEFT BRACKET MISSING) 

17 EDIT ERROR ( LINE EDITING NOT ALLOWED IN EXECUTE) 

17 EDIT ERROR ( NONEXISTENT LINE) 

17 EDIT ERROR ( PREVIOUS INPUT LINE EMPTY) 

17 EDIT ERROR ( OPERATION SUSPENDED, PENDENT, OR MONITORED) 

Explanation: An attempt was made to make an illegal change to a 
suspended, pendent, or monitored operation. 

18 ATTENTION SIGNALED 

Explanation: The attention signal was detected during operation 
execution. 

19 DEVICE DOES NOT EXIST 

Explanation: An invalid device specification was entered. 

20 DEVICE NOT AVAILABLE 

Explanation: The requested device has already been assigned to another 

process. 

2 1 INCORRECT COMMAND 

Explanation: A system command was entered improperly. 

21 INCORRECT COMMAND ( AMBIGUOUS ABBREVIATION) 

Explanation: Not enough characters of a system command were entered 
to distinguish it from other commands. 

21 INCORRECT COMMAND (MISSING SYSTEM COMMAND) 

Explanation: A right parenthesis was entered at the beginning of a line 
and was not followed by a known system command. 

21 INCORRECT COMMAND ( NO SUCH SYSTEM COMMAND) 

2 2 INCORRECT PARAMETER 

Explanation: Invalid syntax was specified for a recognized system 
command. 
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2 2 INCORRECT PARAMETER ( ARGUMENT STRING IS TOO LONG) 

Explanation: The argument entered for ) DO or ) PUSH was more than 
2096 keystrokes. 

2 2 INCORRECT PARAMETER ( CURRENT WORKSPACE CLEARED) 
Explanation: APL failed to load the requested workspace. 

2 2 INCORRECT PARAMETER ( EXTRANEOUS CHARACTERS AFTER COMMAND) 

Explanation: Extra characters were entered after all the required 
parameters for a system command. 

2 2 INCORRECT PARAMETER ( ILL FORMED NAME) 

Explanation: In the argument to ) ERASE or ) GROUP. 

2 2 INCORRECT PARAMETER ( ILL FORMED NUMERIC CONSTANT) 

Explanation: A numeric argument to a system command was entered 
improperly. 

2 2 INCORRECT PARAMETER ( ILLEGAL ASCII CHARACTER) 

Explanation: An illegal character was used in the argument to ) PUSH. 

2 2 INCORRECT PARAMETER ( ILLEGAL NAME CLASS) 

Explanation: A label or system object was used in the argument to 

) GROUP. 

2 2 INCORRECT PARAMETER ( INVALID CHARACTER SET QUALIFIER) 

Explanation: An invalid qualifier was used in the argument to ) INPUT or 
) OUTPUT. 

2 2 INCORRECT PARAMETER ( INVALID KEYWORD OR QUALIFIER) 

Explanation: An invalid keyword or qualifier was used in the argument 

to ) INPUT, ) OUTPUT, ) SAVE, or ) STEP. 

2 2 INCORRECT PARAMETER ( LINE TOO LONG TO TRANSLATE) 

Explanation: The argument entered for ) DROP or ) LIB was greater than 
approximately 2048 keystrokes. 

2 2 INCORRECT PARAMETER ( LOWERCASE QUALIFIER REPEATED) 

Explanation: An invalid repetition of /LOWERCASE was used in the 
argument to ) DO or ) PUSH. 
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22 INCORRECT PARAMETER ( MISSING ARGUMENT) 

Explanation: An argument was not supplied for a system command that 
should have one. 

22 INCORRECT PARAMETER (NOKEYPAD QUALIFIER REPEATED) 

Explanation: An invalid repetition of /NOKEYPAD was used in the 
argument to ) DO or ) PUSH. 

22 INCORRECT PARAMETER (NOLOGICALS QUALIFIER REPEATED) 

Explanation: An invalid repetition of /NOLOGICALS was used in the 
argument to ) DO or ) PUSH. 

2 2 INCORRECT PARAMETER {NO SYMBOLS QUALIFIER REPEATED) 

Explanation: An invalid repetition of /NOSYMBOLS was used in the 
argument to ) DO or ) PUSH. 

2 2 INCORRECT PARAMETER (NOT A GROUP) 

Explanation: An attempt was made to display the contents of a nongroup. 

22 INCORRECT PARAMETER (NOT A LETTER) 

Explanation: The argument to ) NMS, ) VARS, ) FNS, or ) GRPS was not a 
letter. 

22 INCORRECT PARAMETER (NOTIFY QUALIFIER REPEATED) 

Explanation: An invalid repetition of /NOTIFY was used in the argument 
to the ) PUSH command. 

22 INCORRECT PARAMETER (NOWAIT QUALIFIER REPEATED) 

Explanation: An invalid repetition of /NOWAIT was used in the argument 
to the ) PUSH command. 

2 2 INCORRECT PARAMETER ( PARAMETER OUT OF RANGE) 

Explanation: The numeric argument entered for a system command was 
outside the legal range of values for the command. The ranges are: 

For ) DIGITS, 1 to 16 

For ) WIDTH, 35 to 2048 

For ) MAXCORE, the ) MINCORE value to 1048576 

For ) MINCORE, to the ) MAXCORE value 

For ) SAVE/MAXLEN, 512 to 2048 
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2 2 INCORRECT PARAMETER ( PARENT QUALIFIER REPEATED) 
Explanation: In the ) ATTACH command. 

2 2 INCORRECT PARAMETER ( PROCESS NAME QUALIFIER REPEATED) 
Explanation: In the ) PUSH command. 

22 INCORRECT PARAMETER (REDUNDANT KEYWORD OR QUALIFIER) 

Explanation: A keyword or qualifier was repeated in the argument to 

) OUTPUT, ) STEP, or UASS. 

2 2 INCORRECT PARAMETER ( SYSTEM VARIABLE VALUE MAY ONLY BE OR 1) 
Explanation: In the ) ORIGIN command. 

2 2 INCORRECT PARAMETER ( UNRECOGNIZED QUALIFIER KEYWORD) 

2 2 INCORRECT PARAMETER ( WILDCARDS NOT ALLOWED IN FILE SPEC) 

Explanation: A wildcard was used in the name of a workspace identifier. 

2 3 WORKSPACE LOCKED 

2 3 WORKSPACE LOCKED ( INCORRECT PASSWORD) 

2 3 WORKSPACE LOCKED ( WORKSPACE HAS NO PASSWORD) 

Explanation: An incorrect password (or none at all) was given to access a 
workspace that was saved with a password. 

2^ NOT GROUPED, NAME IN USE 

2 5 EXECUTE ERROR 

Explanation: APL signaled an error while executing the argument to the 
£ execute function. 

2 7 LIMIT ERROR 

Explanation: The result of the operation exceeded some implementation 
limit; for example, if the argument array to ( Q FX has more than 6 5 5 3 5 
columns. 

2 7 LIMIT ERROR ( ARGUMENT STRING IS TOO LONG) 

Explanation: The length of an argument cannot be greater than 255 
keystrokes. 

2 7 LIMIT ERROR ( ARGUMENT TOO LARGE) 

Explanation: The argument to Q SF was greater than 255 keystrokes. 
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2 7 LIMIT ERROR ( ARGUMENT TOO LONG) 

Explanation: For ( OMA P, if A contains more than 255 formal parameters 
(including the result). 

2 7 LIMIT ERROR ( AXIS TOO LONG) 

27 LIMIT ERROR ( DELAY VALUE TOO LARGE) 

Explanation: The delay specified for ( □ DL was larger than approximately 
3.4E11 milliseconds. 

2 7 LIMIT ERROR ( FLOATING OVERFLOW) 

Explanation: Arithmetic overflow has occurred. 

2 7 LIMIT ERROR ( INPUT LINE TOO LONG) 

2 7 LIMIT ERROR ( INTEGER TOO LARGE) 

Explanation: A value is greater than the largest allowable integer. 

2 7 LIMIT ERROR ( PARAMETER OUT OF RANGE) 

Explanation: One of the parameters in the left argument of dyadic t is 
less than ~ 127 or greater than 127. 

2 7 LIMIT ERROR ( RANK TOO LARGE) 

27 LIMIT ERROR ( VOLUME TOO LARGE) 

Explanation: The result of a primitive function has more elements than 
the implementation can accomodate. 

28 AXIS RANK ERROR (NOT VECTOR DOMAIN) 

Explanation: The specified axis number argument ( [ #] ) is not a 
singleton and its rank is greater than 1. 

2 9 AXIS LENGTH ERROR 

Explanation: The specified axis number argument has more than one 
item. 

2 9 AXIS LENGTH ERROR ( ARGUMENT RANK AND AXIS INCOMPATIBLE) 

2 9 AXIS LENGTH ERROR ( NOT SINGLETON) 

Explanation: The axis argument is not a singleton. 
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2 9 AXIS LENGTH ERROR ( LEFT ARGUMENT HAS WRONG LENGTH) 

Explanation: The length of the axis argument to + or + does not match 
the length of the left argument. 

3 AXIS DOMAIN ERROR 

Explanation: The specified axis argument value was not a nonnegative 
integer (except in the case of laminate, which accepts floating-point 
numbers greater than ~ l ), or the specified function was not in the domain 
of the axis operator. 

3 AXIS DOMAIN ERROR ( ARGUMENT RANK AND AXIS INCOMPATIBLE) 

Explanation: The axis argument or an element of the axis argument is 
greater than the rank of the argument with the largest rank. 

3 AXIS DOMAIN ERROR ( AXIS LESS THAN INDEX ORIGIN) 
Explanation: The axis argument is less than 010. 

3 AXIS DOMAIN ERROR ( INCORRECT TYPE) 

Explanation: The axis argument is not a number. 

3 AXIS DOMAIN ERROR (NOT AN INTEGER) 

Explanation: The axis argument is not a near-integer. 

3 AXIS DOMAIN ERROR ( SEMICOLON LIST NOT ALLOWED) 

Explanation: There is a semicolon inside the brackets that surround the 
axis argument . 

30 AXIS DOMAIN ERROR ( AXES NOT IN CONTIGUOUS ASCENDING ORDER) 

Explanation: The axis argument elements must be in contiguous 
ascending order for Ravel. 

30 AXIS DOMAIN ERROR ( DUPLICATE AXIS NUMBER) 

Explanation: An axis argument element was specified more than once. 

3 AXIS DOMAIN ERROR ( ENCLOSED ARRAY NOT ALLOWED) 

Explanation: The axis argument must be a simple homogeneous array. 

30 AXIS DOMAIN ERROR ( INCORRECT OPERATION) 

Explanation: An operation was specified that was not one of the 
following: Ravel, Catenate/Laminate, Reverse, Rotate, Expand, Scan, 
Replicate/Compress, Reduce, Monadic Grade up/down, Take, Drop. 
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3 AXIS DOMAIN ERROR ( RIGHT ARGUMENT HAS WRONG RANK) 

Explanation: An axis argument value was specified that is greater than 
the rank of the right argument. 

31 PROTECTION VIOLATION 

Explanation: The protection assigned to the workspace you specified 
prohibits the access you requested. 

31 PROTECTION VIOLATION ( INSUFFICIENT PRIVILEGE OR FILE PROTECTION 

VIOLATION) 

32 INVALID SIMULTANEOUS ACCESS 

Explanation: More than one user tried to save the same workspace 
simultaneously, or a user tried to access a nonshared file that is already in 
use. 

32 INVALID SIMULTANEOUS ACCESS ( FILE CURRENTLY LOCKED BY ANOTHER 
USER) 

3 3 10 ERROR 

3 3 10 ERROR ( INVALID WILDCARD OPERATION) 

Explanation: For ) OUTPUT, a wildcard was specified in place of a value 
for filespec. 

3 3 10 ERROR ( NULL PRIMARY KEY) 

Explanation: An attempt was made to specify an empty key value. 

3 3 10 ERROR ( SEQUENTIAL DELETE OPERATION IS NOT ALLOWED FOR KY 
FILES) 

Explanation: An attempt was made to omit the entire key specification. 

3 4- COMPONENT ERROR 

Explanation: An attempt was made to read a component that cannot be 
read. 

31 COMPONENT ERROR ( COMPONENT CROSSES CELL BOUNDARY) 

3 4 COMPONENT ERROR ( COMPONENT IS DAMAGED) 

3 4- COMPONENT ERROR ( RECORD NOT A COMPONENT) 

3 5 INVALID FILE SPECIFICATION 
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3 5 INVALID FILE SPECIFICATION ( WILDCARDS NOT ALLOWED IN FILE 
SPECIFICATIONS) 

Explanation: Wildcards are invalid in the file specifications for ) INPUT 
and ) OUTPUT. 

3 6 INDEX RANK ERROR 

Explanation: The rank of the index and the argument are not compatible. 

3 6 INDEX RANK ERROR ( CANNOT INDEX A SCALAR ) 

3 7 INDEX LENGTH ERROR 

Explanation: In the form ALK1+B B is not a singleton and its shape does 
not conform to the shape of the selected items of A . 

3 7 INDEX LENGTH ERROR ( INDEX OUT OF RANGE) 

3 8 INDEX DOMAIN ERROR 

3 8 INDEX DOMAIN ERROR ( INCORRECT TYPE) 

Explanation: An attempt was made to enter an index array that does not 
consist of nonnegative integers. 

3 8 INDEX DOMAIN ERROR ( INDEX LESS THAN INDEX ORIGIN) 

3 8 INDEX DOMAIN ERROR ( NOT AN INTEGER) 

Explanation: A value of the axis argument is not a near-integer. 

3 9 NO SUCH DIRECTORY 

40 OPERATOR DOMAIN ERROR (ARRAY OPERAND NOT ALLOWED) 
Explanation: An array was specified as an operand to an each ( " ) or dot 
(.) operator. 

41 NO ROOM ON FILE STRUCTURE OR QUOTA EXCEEDED 

Explanation: The specified file structure was full, or the disk allocation 
was exceeded. In the latter case, files must be deleted from the user's disk 
area before more files can be added. 

42 DEVICE IS WRITE-LOCKED 

Explanation: The specified device (usually a magnetic tape) was 
physically write-protected. 
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4 3 SYSTEM RESOURCES EXHAUSTED 

Explanation: The system ran out of space to perform certain functions for 
the user. See the system manager at your installation. 

4 4 ERROR INVOKING EXTERNAL ROUTINE 

Explanation: An error occurred while trying to map an external routine 
or process the actual arguments before executing the external routine. 

44 ERROR INVOKING EXTERNAL ROUTINE (DOMAIN ERROR) 

Explanation: One of the following situations has occurred: 

• The data leaving the workspace cannot be converted to the data type 
expected by the external routine (for example, numbers could not be 
converted to / TYPE : T). 

• A conversion failed as data passed from the workspace to the external 
routine. 

44 ERROR INVOKING EXTERNAL ROUTINE ( EXTRANEOUS CHARACTERS AFTER 
COMMAND) 

Explanation: Unrecognized input, such as an undefined or repeated 
qualifier, appeared at the end of the command. 

4 4 ERROR INVOKING EXTERNAL ROUTINE ( ILL FORMED NAME) 

Explanation: The actual parameter specified for either the /ACCESS -.OUT 

or / ACCESS: INOUT qualifier is not a valid APL name. 

44 ERROR INVOKING EXTERNAL ROUTINE ( ILLEGAL ASCII CHARACTER) 

Explanation: A conversion to ASCII failed as character data (/TYPE-.T or 
/TYPE: VT left the workspace. 

4 4 ERROR INVOKING EXTERNAL ROUTINE ( ILLEGAL NAME CLASS) 

Explanation: The actual parameter specified for either the /ACCESS-.OUT 

or /ACCESS: INOUT qualifier is defined, but is not a variable. 

4 4 ERROR INVOKING EXTERNAL ROUTINE ( INCORRECT PARAMETER) 
Explanation: One of the following situations has occured: 

• The actual parameter specified for either the /ACCESS-.OUT or 
/ACCESS-.INOUT qualifier is currently undefined and is /TYPE: Z. The 
parameter must either be defined so an unconverted value can be 
passed or undefined with a known data type, not / TYPE : Z 
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• The actual argument is missing when the formal paramter is specified 
with the /MECHANISM: IMMEDIATE qualifier. 

1+1+ ERROR INVOKING EXTERNAL ROUTINE ( INCORRECT TYPE) 

Explanation: The actual paramter specified for either the /ACCESS -.OUT 

or /ACCESS: INOUT qualifier is not a character. 

1+1+ ERROR INVOKING EXTERNAL ROUTINE ( LENGTH ERROR) 
Explanation: One of the following situations has occurred: 

• The actual argument has a length greater than 4 bytes when UMAP was 
specified with the /MECHANISM -.IMMEDIATE qualifier. 

• The actual argument has a length greater than 2+ 2* 16 when dyadic 
DMAP was specified with the /MECHANISM: DESCRIPTOR qualifier. 

• A complex data type is being passed an odd number of items (APL 
requires two numbers to form each complex number). 

• The length of a Varying sTring ( / TYPE : VT ) is greater than ~ 1+ 2 * 1 6 . 

4 4 ERROR INVOKING EXTERNAL ROUTINE ( NOT VECTOR DOMAIN) 

Explanation: The actual parameter specified for either the /ACCESS-.OUT 
or /ACCESS-.INOUT qualifier is not in the vector domain. 

44 ERROR INVOKING EXTERNAL ROUTINE ( NOT SINGLETON) 

Explanation: The actual argument is not a singleton (as it should 
be) when dyadic ( DMAP is specified with the /MECHANISM: IMMEDIATE 
qualifier. 

44 ERROR INVOKING EXTERNAL ROUTINE ( WRONG NUMBER OF ARGUMENTS TO 
USER FUNCTION) 

Explanation: More actual arguments were specified than there are formal 
parameters defined in the formal parameters of the external routine. 

4 5 SIGNAL FROM EXTERNAL ROUTINE 

Explanation: An external routine signaled the error that is the secondary 
error message. 

46 OPERATION INVALID IN THIS CONTEXT 

Explanation: An attempt was made to use ) STEP when there was no 
suspended operation. 

47 OUTPUT LINE TOO LONG 
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4 7 OUTPUT LINE TOO LONG ( BUFFER OVERFLOW) 

Explanation: A line editing sequence created a line that was too long to 
fit in the I/O buffer. 

47 OUTPUT LINE TOO LONG ( PAGE WIDTH EXCEEDED) 

Explanation: A line editing sequence created a line longer than the page 
width limit. 

4 8 INPUT LINE TOO LONG 

48 INPUT LINE TOO LONG ( ARGUMENT STRING IS TOO LONG) 
Explanation: The argument to ) HELP was longer than APL's input buffer. 

4 9 FILE CONTAINS A DAMAGED WORKSPACE 

Explanation: The file specified by ) LOAD, ) COPY, or ) PCOPY contains a 
damaged workspace. 

49 FILE CONTAINS A DAMAGED WORKSPACE ( CURRENT WORKSPACE CLEARED) 

Explanation: An attempt was made to load a file that contains a damaged 
workspace. The current workspace is cleared. 

5 CHARACTER ERROR 

Explanation: The user entered an illegal overstruck character. 

5 CHARACTER ERROR ( ILLEGAL CHARACTER IN EXPRESSION) 

Explanation: An internal ( □ A V code was included outside of a literal or 
comment. 

50 CHARACTER ERROR ( ILLEGAL OVERSTRIKE) 

51 INPUT ABORTED 

Explanation: The user entered the abort signal to escape from quad, 
quote quad, or quad del input. 

5 2 FUNCTION EDITING ABORTED 

Explanation: The user entered the abort signal to escape from the 
function editor. 

5 3 LINE EDITING ABORTED 

Explanation: The user entered the abort signal to escape from character 
editing mode. 
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5 4 INTERNAL ERROR SAVING WORKSPACE 

Explanation: An internal inconsistency was detected. Please notify your 
Digital software specialist. 

5 5 NOT A RANDOM ACCESS DEVICE 

5 6 INCORRECT MODE FOR DEVICE 

Explanation: The I/O mode for the operation requested was improper for 
the chosen device. 

5 7 FILE DOES NOT CONTAIN A WORKSPACE 

Explanation: An attempt was made to load or copy a file that does not 
contain an APL workspace. 

5 7 FILE DOES NOT CONTAIN A WORKSPACE ( CURRENT WORKSPACE CLEARED) 

58 DATA TRANSMISSION ERROR 

Explanation: A data transmission error was detected during input or 
output. This message is usually associated with a nonrecoverable device 
error. 

5 9 FILE ALREADY EXISTS WITH GIVEN NAME 

Explanation: An attempt was made to save a workspace with the same 
file name as an existing file that is not a workspace. 

6 WS NOT SAVED, THIS WS IS wsname 

Explanation: An attempt was made to save a workspace with the same 
file name as an existing workspace, without first making that same name 
the workspace identification (returned by ) WSID ) . This error message is 
to prevent inadvertent overwriting of previously saved workspaces. 

6 2 NOT A DIRECTORY STRUCTURED DEVICE 

6 3 FILE ASSIGNED READ ONLY 

6 4 CHANNEL NOT ASSIGNED 

Explanation: The channel specified in a file operation was not previously 
associated with a file via a OASS system function. 

6 5 CHANNEL CANNOT DO BOTH INPUT AND OUTPUT 

Explanation: An attempt was made to do both input and output to a 
channel assigned to a sequentially organized file. 
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6 6 NOT AN INPUT DEVICE 

Explanation: The user tried to perform input from an output-only device, 
such as a line printer. 

6 7 NOT AN OUTPUT DEVICE 

Explanation: The user tried to perform output from an input-only device, 
such as a card reader. 

6 8 END OF FILE ENCOUNTERED 

Explanation: A sequential read operation was attempted when there was 
no next record or component and when the channel was assigned with 
/SIGNAL. 

6 9 RECORD NOT FOUND 

Explanation: A random read operation was attempted on a nonexistent 
record or component when the channel was assigned with /SIGNAL. 

71 DEVICE ERROR 

Explanation: A file operation attempted to use a mode that is improper 
for the device specified in the associated UASS function.) 

72 SYSTEM SERVICE FAILURE 

7 3 SUBPROCESS ERROR 

7 3 SUBPROCESS ERROR ( COMMAND BUFFER OVERFLOW - SHORTEN EXPRESSION 
OR COMMAND LINE) 

7 4 BLOCK TOO BIG 

Explanation: A data-transfer error occurred during I/O. Specifically, the 
last read attempted to read a block of data that was too large. 

75 

Explanation: The end of the file was reached when /SIGNAL was not 
being used. No message is printed and execution continues. 

7 6 RESULT ERROR (BRANCH HAS NO RESULT) 

Explanation: Branch was used with Q input. 

7 7 STOPSET 

Explanation: The operation was suspended because a stop bit was set for 
the current line. 
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7 8 END OF TAPE 

Explanation: The end of a reel of magnetic tape was reached. 

7 9 SYSTEM FUNCTION ILLEGAL IN EXECUTE 

Explanation: The ( □ BREAK system function was used in the argument to 
the execute function. 

8 RETURN TO CALLER OF THIS IMAGE 

Explanation: The right argument to ( Q SIGNAL was 80. 

81 BROADCAST RECEIVED 

Explanation: A broadcast was received when ( DGAG was set to 3 . 

8 2 CHANNEL NUMBER IS NOT AVAILABLE 

8 3 DAMAGED WORKSPACE HAS BEEN CORRECTED 

8 3 DAMAGED WORKSPACE HAS BEEN CORRECTED (SOME SYMBOLS MAY HAVE 
BEEN ERASED) 

Explanation: A workspace, which previously contained corrupted data, 
was loaded with the / CHECK qualifier. 

8 6 FILE IS ASSIGNED WRITE ONLY 

10 HI FILE READ ERROR 

Explanation: An error occurred while reading the file specified by the /HI 
qualifier on an APL command line or in an initialization file. 

101 INITIAL WORKSPACE NOT FOUND 

Explanation: The workspace that was specified on the APL command line 
or in the initialization file was not found by APL. 

10 2 VECTOR PROCESSOR NOT AVAILABLE 

10 3 ERROR IN INITIALIZATION FILE 

Explanation: APL detected an error while processing the parameters in 
the initialization file identified by the logical name APL$INIT. 

10 4 NEGATIVE THRESHOLD WITH VECTOR QUALIFIER NOT ALLOWED 

10 5 ERROR INITIALIZING CONSOLE CHANNEL 

106 ERROR INITIALIZING WORKSPACE ENVIRONMENT 
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108 FATAL INITIALIZATION ERROR 

109 FATAL ERROR SETTING UP CLEAR WORKSPACE 

110 ERROR READING INPUT FILE 

111 EDIT COMMAND ERROR 

111 EDIT COMMAND ERROR ( XX QUALIFIER REPEATED) 

Explanation: For ) EDIT, the same qualifier was specified more than 
once, xx is the name of the repeated qualifier. 

Ill EDIT COMMAND ERROR ( ARGUMENT TO xx IS OUT OF RANGE) 

Explanation: For ) EDIT, a numeric value that is outside the acceptable 
range was specified for a qualifier, xx is the name of the qualifier. 

Ill EDIT COMMAND ERROR ( BAD ARGUMENT TO XX) 

Explanation: For ) EDIT, an invalid value was specified for a qualifier, xx 
is the name of the qualifier. 

Ill EDIT COMMAND ERROR ( CANNOT EDIT SYSTEM SYMBOL) 

111 EDIT COMMAND ERROR ( EDIT COMMAND UNAVAILABLE DURING FUNCTION 
DEFINITION) 

111 EDIT COMMAND ERROR ( ENCLOSED ARRAY NOT ALLOWED) 

Explanation: An attempt was made to edit an enclosed array. 

Ill EDIT COMMAND ERROR ( EXECUTE QUALIFIER ARGUMENT IS TOO LONG) 

Explanation: For /EXECUTE, the string specified for tpucommand is too 
long. 

Ill EDIT COMMAND ERROR ( ILL FORMED NUMERIC CONSTANT) 

Explanation: For ) EDIT, there is nonnumeric data (data unacceptable to 

D VI) inside a numeric array that is returning from VAXTPU. 

Ill EDIT COMMAND ERROR ( ILL FORMED NUMERIC MATRIX) 

Explanation: For ) EDIT, a record or records in the matrix returning from 
VAXTPU have either more or fewer values than the number of values in 
the first record. 

Ill EDIT COMMAND ERROR ( ILLEGAL ASCII CHARACTER) 
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111 EDIT COMMAND ERROR ( ILLEGAL NAME CLASS) 

Explanation: For /NC, either a value other than 2, 3, or 4 was specified, 
or the specified value does not match the current name class value for 
objectname. 

Ill EDIT COMMAND ERROR ( INCORRECT PARAMETER) 

Explanation: For ) EDIT, an unknown parameter was specified. 

Ill EDIT COMMAND ERROR (MISSING ARGUMENT) 

Explanation: For ) EDIT, an attempt was made to edit a system function 
or variable. 

Ill EDIT COMMAND ERROR ( OPERATION LOCKED) 

Explanation: For ) EDIT, an attempt was made to edit a locked function. 

Ill EDIT COMMAND ERROR (OPERATION SUSPENDED, PENDENT, OR 
MONITORED) 

111 EDIT COMMAND ERROR ( UNBALANCED DELIMITER) 

111 EDIT COMMAND ERROR ( UNRECOGNIZED QUALIFIER KEYWORD) 

111 EDIT COMMAND ERROR ( UNSUPPORTED TERMINAL TYPE) 

111 EDIT COMMAND ERROR ( VOLUME TOO LARGE) 

112 ERROR PROCESSING HELP 

112 ERROR PROCESSING HELP ( INVALID KEY) 

112 ERROR PROCESSING HELP ( TOO MANY HELP KEYS SPECIFIED) 

112 ERROR PROCESSING HELP ( ERROR OPENING AS INPUT) 

Explanation: The file that was specified as the argument to the ) HELP 
command did not exist. 

112 ERROR PROCESSING HELP ( ERROR PARSING ARGUMENT TO LIBRARY) 

Explanation: The value for filespec on the /LIBRARY qualifier was either 
not specified or specified incorrectly. 

113 WATCH POINT ACTIVATED 

113 WATCH POINT ACTIVATED ( VARIABLE HAS BEEN MODIFIED) 
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113 WATCH POINT ACTIVATED ( VARIABLE HAS BEEN MODIFIED BY INDEX) 

113 WATCH POINT ACTIVATED ( VARIABLE HAS BEEN REFERENCED) 

114 ERROR PROCESSING ATTACH 

Explanation: An error occurred when APL attempted to process the 
) ATTACH command. 

114 ERROR PROCESSING ATTACH ( ATTACH REQUEST REFUSED) 

Explanation: The value specified for process-name is the name of a 
nonexistent process. 

114 ERROR PROCESSING ATTACH ( NONEXISTENT PROCESS) 

114 ERROR PROCESSING ATTACH ( INVALID LOGICAL NAME) 

115-499 are reserved for VAX APL 

5 0—999 are for user-defined error messages. 

Explanation: For more information, see Q SIGNAL. 
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abort input signal 

A technique for escaping to immediate mode when APL is waiting for input. 
Different terminals form the abort input signal differently. Consult the index 
to find more information on this subject. 

ambivalent function 

A function that may be monadic or dyadic, depending on how many arguments 
are supplied when it is invoked. 

APL terminal 

A terminal that has an APL keyboard, that is, a terminal that can be set 
up to use the APL key-paired (typewriter-paired), APL bit-paired, or APL 
COMPOSITE character set. 

argument 

An array that is manipulated by a function. APL functions take zero, one, or 

two arguments. 

array 

Any number (including or 1) of items treated as a unit. 

assignment 

A method for associating a name with an array. 

atomic vector 

An array, returned by the system function QAV, that contains all the characters 
in the APL character set. 
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attention signal 

A technique for suspending the execution of an operation and escaping to 
immediate mode. The weak attention signal (formed by pressing (Ctrl/C) once) 
means suspend execution of the current operation after executing the current 
statement, and return control to immediate mode. The strong attention signal 
(formed by pressing (Ctrl/C)) twice, means suspend the current operation as 
soon as possible, even in the middle of the statement, and return control to 
immediate mode. 

axis 

A dimension along which items in an array are arranged. 

Boolean 

A numeric item that has the value or 1. 

branch 

Within a user-defined operation, a change in the normal order of statement 

execution. 

canonical representation 

A character matrix with rows consisting of the original lines of a user-defined 
operation. 

channel 

The logical path through which the APL file system interacts with external 
files and mailboxes. 

character-editing mode 

While in function-definition mode, a mode of editing in which you can edit 
individual characters in a line. 

command line 

The line that contains the DCL command APL. You enter the command line in 
response to the DCL prompt ($). 

comment 

Ignored characters appearing to the right of (and on the same line as) the 
a symbol; you can place a comment at the end of a line containing APL 
statements or on a separate line. 
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comparison tolerance 

An amount used by APL when it calculates how much two numbers can 
differ and still be considered equal. The system variable Q CT contains the 
comparison tolerance used by APL. 

component 

In an external file, a record that contains an APL object. 

constant 

An item whose value is literally the constant itself. 

dense sequence 

For some functions, APL requires that an argument of nonnegative integers 
must form a dense sequence, beginning at D 10. This means that the smallest 
element in the argument must be Q 10, and that an integer N from the 
argument domain may be included only if N- l is also included. For example, if 
the argument domain is the integers from 1 to 3, the arguments 2 1 3, 1 2 2, 
and 111 form dense sequences, but the arguments 131 and 3 2 3 do not. 

depth 

The degree of nesting of an array. 

derived function 

A function that results from the combination of an operator and its operand or 
operands. 

domain 

The permissible type, shape, and values of a function's argument arrays or the 
permissible objects of an operator's operands. 

dummy argument 

In the header of a user-defined operation, an identifier that serves as a 
placeholder for the actual argument, operand, or result that is supplied when 
the operation is called. 

dyadic function 

A function that takes both a left and a right argument. 

enclosed array 

An arrav that includes one or more arravs. 



Glossary-3 



empty array 

An array that has a type and shape but no items. The length of the array 
along at least one axis is 0. 

error trapping 

Techniques to find and react to errors that occur during the execution of 
user-defined operations. 

event flag 

A shareable indicator, accessible through the APL file system, intended to aid 
in synchronizing access to shared files or mailboxes. 

execute-only APL 

The DCL command APL/EXECUTE_ONLY [parameters] invokes the run-time 
support version of VAX APL called QAPL. QAPL can execute applications 
written in VAX APL but does not contain the features to develop applications. 
QAPL can be copied to any valid VMS system free of charge. 

expression 

An identifier or constant standing alone, a function or operator and its 
arguments, or an expression enclosed in parentheses. 

external data 

Data created outside of APL. 

external routine 

A routine (not written in APL) that exists outside the APL environment. APL 
can call library routines and other external routines that support the VAX 
Procedure Calling and Condition Handling Standard. APL cannot call VMS 
system services routines. 

fill element 

A scalar data element (either a space or a 0) inside a fill item. 

fill item 

An array (consisting of spaces, zeros, or a combination of both) that APL 
inserts into another array. The shape and contents of a fill item are based on 
the prototype of the array that APL is using as a model for the array being 
built. Fill items are used by Take, Replicate, Expand, Disclose, and DBOX. 
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function 

An operation that applies to arrays and produces an array as a result. 

function-definition mode 

An operating mode in which the lines of APL you enter are not executed 
immediately but rather are stored for later execution. Function-definition 
mode begins when you type a v and ends when you type a second V or ¥ . This 
mode is used when creating user-defined functions and operators. 

global symbol 

A symbol that has the same value inside and outside a user-defined operation. 

header 

The initial line of a user-defined operation. See operation header for more 
information. 

heterogeneous array 

An array that contains both character and numeric data. 

high minus 

The symbol (" ) used to represent the negative sign in APL. 

homogeneous array 

An array that contains either character or numeric data, but not both. 

identifier 

A variable name, label name, group name, or user-defined operation name. See 
also system identifier. 

identity element 

A value (if one exists) to a dyadic function which, when used as one argument 
to the function, does not change the value of the other argument. For example, 
for any identity element i applied to a dyadic function f and an argument a, a 
does not change: i fa<--+a 

identity function 

A function that APL applies to the prototype of an array when performing the 
reduction (f/B) of an axis that has length zero. Note that the inner product 
(f.g) derived functions imply the use of reduction. The identity function 
is applied to the prototype of the argument array in place of the specified 
function. 
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immediate mode 

An APL operating mode in which lines are executed immediately after they are 
entered. 

index 

A notation used to specify the position of items within an array that you want 
to reference. The index appears immediately to the right of an array and 
consists of two brackets enclosing values that correspond to axes in the array. 
Index is synonymous with subscript. 

indexed assignment 

The assignment of values to selected items of a variable. The indexed variable 
is positioned to the left of the assignment arrow (+■ ), and the index specifies 
the items in the array where the assignment is applied. Indexed assignment is 
synonomous with subscripted assignment or indexed specification. 

index origin 

The starting point for the index values of an array. The index origin may be 
or 1. The system variable Q 10 contains the current index origin value. 

indexing 

The use of an index to access particular items from an array. 

initialization file 

A file, referenced by the VMS logical name APL$INIT, that contains 
parameters that are processed when APL is initialized. 

initialization stream 

Either the DCL command line that invokes APL, or the initialization file 
referenced by the VMS logical name APL$INIT. Either or both of these streams 
may contain parameters to be processed when APL is initialized. 

integer 

Any of the positive and negative integers, or zero. 

internal data 

Data stored in one of the four APL internal data type formats. 
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key 

A field defined by its location and length within each record and used to sort 
the records. At least one key, called the primary key, must be defined for a 
keyed file. Optionally, additional keys, called alternate keys, may be defined. 

key of reference 

The specific key used in a sequential or random read of a keyed file. 

keyed file 

A file in which records are organized by fields, called keys, inside the records. 
The VAX RMS term is indexed sequential file organization (ISAM). The keys 
of the file define the order in which the records are retrieved; you can retrieve 
records sequentially by one of the sorted orders or randomly by one of the 
record's key values. A keyed file must contain at least one key. 

label 

An identifier associated with a line in a user-defined operation. 

latent expression 

A character vector representing an APL expression; the expression is 
associated with a workspace and is automatically executed when the 
workspace is loaded. The system variable Q LX contains the value of the 
workspace's latent expression. 

line 

The statement or statements you enter beginning after an APL input prompt 
and ending when you press Return to enter the line. 

local symbol 

A symbol that has significance only during the execution of a particular 
user-defined operation. 

locked operation 

An operation definition that cannot be changed or displayed. 

logical name 

A symbolic name for any portion or all of a file specification. 

mailbox 

A virtual device useful for sending messages to other processes. 
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matrix 

An array consisting of any number of items arranged along two axes, 
commonly called rows and columns. 

matrix domain 

A matrix, vector, or singleton. 

monadic function 

A function that takes one argument. 

monitored operation 

A user-defined operation that has some of its lines being monitored via 

D MONITOR. 

multikey file 

A file in which records are organized by fields, called keys, inside the records. 
The RMS term is indexed sequential file organization (ISAM). The keys of 
the file define the order in which the records are retrieved: you can retrieve 
records sequentially by one of the sorted orders or randomly by one of the 
record's sort values. A multikey file must contain at least one key. 

near-integer 

A numeric item whose floor is equal to its ceiling; this includes all numbers 
sufficiently close to an integer as determined by the APL comparison tolerance. 

nested array 

A synonym for enclosed array. 

next record pointer 

An internal mechanism that keeps track of the next record to be processed by 
a sequential input function. 

niladic function 

A function that takes no arguments. 

non-APL terminal 

A terminal that does not have an APL keyboard. On such a terminal, APL 
characters must be represented by ASCII mnemonics. 

nonnegative integer 

Any of the positive integers or zero. 
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operation 

Either a function or an operator. Occasionally, operation refers to a 
mathematical action (such as the addition operation) or to an action taken by 
the APL interpreter. 

operation body 

The executable lines of APL that appear in a user-defined operation definition. 

operation header 

The first line you enter when you define an operation. It names the operator; 
indicates whether the operation returns a value; indicates whether the 
operator is monadic or dyadic; indicates the use of an axis argument; and 
identifies the operation's local symbols. 

operator 

An operation that is applied to either arrays, or functions, or both and 
produces a derived function as a result. In VAX APL, there are user-defined 
operators and primitive operators. 

operator sequence 

A sequence of functions and operators whose result is a derived function. 

overstruck character 

An APL character formed by combining two other APL characters. For 
example, the @ symbol is formed with the □ and «- symbols. Different terminal 
types form overstrikes in different ways. Some terminals allow you to enter 
the first character, use Backspace, and then enter the second character on top 
of the first. Other terminals allow you to use a Compose Character key (or 
Ctrl/D) and then to enter the two characters. On these terminals, only the 
resulting overstrike character is displayed. 

panic exit 

A technique for immediately suspending the execution of an operation and 
giving control to the operating system. The panic exit is formed by pressing 
Ctrl/Y once. After a panic exit, you can return to where you left off by 
executing the DCL command CONTINUE. If you enter the panic exit while 
an operation is executing, the operation is suspended; if you then enter 
CONTINUE, the operation resumes execution at the point where it was 
interrupted. 
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pendent operation 

A user-defined operation that has called another operation and is waiting for 
that operation to return. 

pervasive operation 

An operation that acts at all depths (levels of nesting) of an array. 

PID 

Process Identification, an integer value that uniquely identifies a VMS process. 

positive integer 

The integers greater than zero. 

print precision 

The maximum number of significant digits displayed in floating-point output. 
The system variable Q PP contains the current print precision value. 

print width 

The maximum number of characters that APL can display on a terminal 
output line. The system variable Q PW contains the current print width value. 

process 

The basic entity scheduled by VMS software that provides the context in which 
an image executes. 

process identification 

An integer value that uniquely identifies a VMS process. 

prototype 

An array that APL uses to determine the shape and contents of fill items. 
The prototype of an array B has the same shape as the first item of B and 
has character blanks and zeros in positions corresponding to characters and 
numbers, respectively, in the first item of B . 

pure data record 

A record that is a vector of values, with none of the embedded format 
information that APL includes within component data records. 

quiet function 

A function that does not return a value unless one is needed; that is, a value is 
returned only if it is not the leftmost function. 
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random link 

The current value used by the APL random number generator. The system 
variable □ RL contains the current random link value. 

range 

The permissible type, shape, and values of a function's result array. 

rank 

The number of axes along which an array's items are arranged. 

recursive operation 

A user-defined operation that calls itself. 

reshape 

A function used to change the number of an array's axes or to change the 
length of one or more of its axes. 

row-major order 

An ordering of the items of an array so that the last subscript value varies 
most rapidly. For example, the row-major order of a 2 by 3 matrix would be 
[1;1], [1;2], [1;3], [2;1], [2;2], [2;3]. 

scalar 

A rank array (an array with no axes) containing a single numeric or 
character or enclosed item. 

scalar extension 

An implicit operation that reshapes a scalar argument to match the shape of a 
non-scalar argument. 

scalar product 

An implicit operator that applies a dyadic scalar function over each 
corresponding pair of items in the two arguments. 

selective assignment 

A method for replacing selected items of an array. 
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shadow 

The act of localizing a name when a user-defined operation is activated so 
that the old value of the name is saved and the name becomes undefined 
in the context of the newly activated user-defined operation. The old value 
of the name is restored when the user-defined operation exits to its calling 
environment. 

shape 

The way an array's items are arranged; specifically, a numeric vector that 
describes the length of each of the array's axes. 

signal 

A term often used in the description of what APL does when it detects an 
error; APL signals an error. 

simple array 

An non-enclosed array whose depth is less than 2. 

simple scalar 

A scalar that contains only a single character or number. 

singleton 

A one-item array of any rank (includes scalars). 

singleton extension 

An implicit operation that is applied to a dyadic scalar function when one 
or both of the function's arguments are singletons. This implicit operator 
reshapes the singleton argument to match the shape of the nonsingleton 
argument, allowing the single value from the singleton to be applied to 
each item of the other argument. When both arguments are singletons, the 
argument with the smaller rank is reshaped to match the rank of the other 
singleton. 

specification 

A method for associating a name with an array. 

state indicator 

A vector that reports the status of user-defined operations, quad input 
requests, and execute functions. 
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statement 

One or more expressions executed as a unit. 

stop bit 

A setting associated with a line in an operation definition that causes the 
operation to be suspended before the line is executed. 

strand 

Two or more juxtaposed arrays (including scalars) which form a vector. Also 
known as vector notation. 

strand assignment 

The process of associating a strand of values with a set of names. 

subprocess 

A process created by and subordinate to another process. The subprocess 
shares the resources of the creating process. 

subscript 

A notation used to specify the position of items within an array that you want 
to reference. The subscript appears immediately to the right of an array and 
consists of two brackets enclosing values that correspond to axes in the array. 
Subscript is synonymous with index. 

subscripted assignment 

An assignment that modifies only the items that are specified by an index list. 
Subscripted assignment is synonymous with indexed assignment or subscripted 
specification. 

suspended operation 

A user-defined operation that has stopped executing but still has lines of APL 
to be processed. 

symbol table 

A data structure inside the APL interpreter. The symbol table keeps track of 
the names of all objects in a workspace. 

system identifier 

Any system-provided name that always begins with the quad (Q ) symbol. 
System identifier refers to system variables and functions. 
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Index 



Abbreviations for system commands, 3-2 

Absolute value, 1-14 

Accounting information system function, 

2-13 
Accumulating data system function, 2-44 
Addition function, 1-16 
Alphabetic characters 

vector of, 2—14 
Alphabetics 

lowercase, 2-15 

system function, 2-14 

underscored, 2—16 
Ambivalent system functions, 2-7 
And function, 1-21 
APL character set, 2-^47 
APL session 

exiting from, 3-A, 3-13, 3-60 

interrupting, 3-4 
Arbitrary output, 2-17 
Arguments 

multiple 

in user-defined ops, 1-219 

scalar function, 1-2 
Arithmetic functions, 1-10 
Array corner, 1-59, 1-156 
Arrays 

displaying, 2-62 

joining, 1-34 

matrix product of, 1-209 

rank of, 1-150 

shape of, 1-138 

sorting, 1-87, 1-90, 1-96, 1-99 



ASCII 

character set system variable, 2-19 

control characters, 2—58 

output, 2-17 
Assigning files system function, 2-20 
Assignment 

selective, 1-221 

strand, 1-218 
Associative argument with scan, 1-203 
Atomic vector system function, 2-32 
Automatic save system variable, 2-28 
Axis, 1-212 

B 

Backslash operator, 1-178 
Bare output 

resetting buffer, 2-18 
Base function, 1-27 
BETA function, 1-20 
Bit-paired character set, 2-47 
Box system function, 2-35 
Branch function, 1-31 
Break system function, 2-38 
Breakpoint, 2-38 
Brief error messages, 2—183 
Buffer 

resetting bare output, 2-18 
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Canonical representation, 2-98 

system function, 2—54 
Catenate function, 1-34 
Channels 

assigning files to, 2-20 

listing active, 2-40 

status of, 2-41 

system function, 2^10 
Character arrays 

converting to, 1-79 
Character matrix 

from character vector, 2-35 
Character set 

APL, 2-47 

atomic vector table, 2-32 

bit-paired, 2-47 

composite, 2-47 

key-paired, 2-47 

TTY, 2-47 
Character string 

executing, 1-70, 2-221 

selecting numbers from, 2-89, 2-203 
Character vector 

from character matrix, 2-35 
Characters 

ASCII control, 2-58 

converting to numbers, 2-88 

digits, 2-135 

fill, 1-179, 1-196, 2-86, 2-161 

nonprintable, 2-32 

vector of alphabetic, 2—14 
Circle function, 1-17 
Clear event flag system function, 2-77 
Clear workspace 

characteristics, 3—11 
Closing files system function, 2-52 
Combinations function, 1-19 
Comparing numbers, 2-56 
Comparison tolerance, 1-12, 1-13 

system variable, 2—56 
Composite character set, 2^17 



Compresssion function, 1—179 
Conditional branching, 1—32 
Conjugate function, 1-10 
Connect time, 2—13 
Contains function, 1-43 
CONTINUE workspace, 3-13 
Control characters 

ASCII, 2-58 
Control characters system function, 2-58 
Controlling output, 1-82 
Convert characters system function, 2-88 
Copy 

protected, 3-72 
Corner of an array, 1-59, 1—156 
CPU time, 2-13 
Current date, 2-197 
Current time, 2-197 



Data 

packing, 2-46, 2-138 

reformatting, 2-93 

treating a function as, 2—54 

unpacking, 2-46, 2-138 
Date, 2-197 
DCL 

command execution, 3—19, 3-74 
Deal function, 1-45 
Debugging 

stepping through operations, 3—85 
Decode function, 1-27 
Defaults 

in clear workspace, 3-11 

of system variables, 2—2 
Delay system function, 2-70 
DELETE command 

VMS, 3-21 
Depth function, 1-47 
Derived functions 

compression, 1-179 

expansion, 1-196 

inner product, 1—208 

outer product, 1-205 

reduction, 1-185 
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Derived functions (cont'd) 

replication, 1-179 

scan, 1-201 
Device 

displaying characteristics of, 2-74 

mailbox number of, 2-120 
Diagonal slice, 1-165 
Difference (subtraction), 1-16 
Digits, 2-135 

significant, 2-142 
DIRECTORY, DCL command, 3-19 
Disclose function, 1-49 
Display control system variable, 2-62 
Display format, 1-79 
Displaying enclosed arrays, 2-62 
Displaying workspace information system 

command, 3—68 
Distinguished names, 2-2, 2-4 
Division 

by zero, 1-16 

matrix, 1-116, 1-119 
Division function, 1—16 
Domain of functions, 1-1 
Domino, 1-120 
Dot operator, 1—178 
Drop function, 1-58 
Dyadic format function, 1-82 
Dyadic functions, 1-1 

scalar, 1-3 
Dyadic grade down function, 1-90 
Dyadic grade up function, 1-99 
Dyadic transpose function, 1-164 



Each operator, 1-191 
Editing with VAXTPU, 3-22 
Enclose function, 1-63 
Encode function, 1—135 
Enlist function, 1-69 
/ENTRY qualifier, 2-118 
Equal to function, 1—22 
Erasing global names, 3-28 
Erasing named objects system function, 
2-83 



Error messages, A-l 

brief, 2-183 

secondary, 2-183, A-l 

text of, 2-80 
Error number, 2-173 
Errors 

signaling, 2-172 
Exclusive OR operation, 1—22 
Execute function, 1-70 
Executing expressions system function, 

2-221 
Execution 

monitoring, 2-192 

of DCL commands, 3-19, 3-74 

of VMS commands, 3-74 

status of, 3-84 
Expansion function, 1—196 
Expansion system function, 2—85 
Exponential function, 1-11 
Expressions 

automatic execution of, 2—108 

executing, 2—221 
External routines 

defining to APL, 2-111 

querying APL definition, 2-111 



Factorial function, 1-14 

File assignments, listing, 2-20 

File organization qualifiers, 2-21 

File status, 2-41 

Files 

closing, 2-52 

deassigning, 2-60 

deleting, 3-21 

organization of, 2—41 

sharing, 2-91 
Fill character, 1-179, 1-196, 2-86, 2-161 
Fill items, 1-155 
First function, 1-77 
Fix function system function, 2-98 
Floor function, 1-12 
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Form character matrix system function, 

2-35 
Form character vector system function, 2-35 
Format 

of output display, 1-79 
Format function 

dyadic, 1-82 

monadic, 1-79 
Format system function, 2-7 
Function characteristics 

domain, 1-1 

range, 1-1 
Function names 

displaying, 3-31 

list of, 2-131 
Functions, APL 

quotient, 1-16 
Functions, APL primitives 

addition, 1-16 

and, 1-21 

base, 1-27 

BETA, 1-20 

branch, 1-31 

catenate, 1-34 

ceiling, 1-13 

circle, 1-17 

combinations, 1—19 

compression (derived), 1-179 

conjugate, 1—10 

contains, 1—43 

deal, 1-45 

decode, 1-27 

depth, 1-47 

disclose, 1-49 

division, 1—16 

drop, 1-58 

dyadic format, 1—82 

dyadic grade down, 1-90 

dyadic grade up, 1-99 

dyadic transpose, 1-164 

enclose, 1-63 

encode, 1-135 

enlist, 1-69 

equal to, 1-22 

execute, 1-70 



Functions, APL primitives (cont'd) 
expansion (derived), 1-196 
exponential, 1-11 
factorial, 1-14 
first, 1-77 
floor, 1-12 
GAMMA, 1-14 
greater than, 1-22 
greater than or equal, 1-22 
index generator, 1-105 
index of, 1-107 
inner product (derived), 1-208 
intersection, 1-110 
laminate, 1—34 
less than, 1-22 
less than or equal, 1-22 
logarithm, 1-12, 1-17 
magnitude, 1-14 
match, 1-113 
matrix divide, 1-116 
matrix inverse, 1—119 
maximum, 1-18 
membership, 1-121 
minumum, 1—18 
monadic format, 1—79 
monadic grade down, 1—87 
monadic grade up, 1-96 
monadic transpose, 1-161 
multiplication, 1-16 
nand, 1-21 

natural logarithm, 1-12 
negative, 1-11 
nor, 1-21 
not, 1-21 
not equal, 1-22 
or, 1-21 

outer product (derived), 1-205 
overtake, 1—154 
pi times, 1-12 
pick, 1-123 
power, 1-16 
ravel, 1-130 
reciprocal, 1—11 
reduction (derived), 1-185 
replicate (derived), 1—179 
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Functions, APL primitives (cont'd) 

replication (derived), 1—179 

represent, 1-135 

reshape, 1-138 

residue, 1-18 

reverse, 1—141 

roll, 1-14 

rotate, 1-145 

scan (derived), 1—201 

shape, 1-149 

signum, 1—11 

specification, 1-215 

subset, 1-152 

subtraction, 1—16 

take, 1-154 

union, 1—170 

unique, 1-172 

without, 1-174 
Functions, system 

see System functions 
Functions, types of 

arithmetic, 1—10 

dyadic, 1-1 

dyadic scalar, 1-3 

locked, 3-81 

logical, 1-21 

mixed, 1-1 

monadic, 1-1 

monadic scalar, 1-2 

pendent, 3-80 

primitive mixed, 1-22 

quiet, 2-8 

relational, 1-22 

scalar, 1—1, 1-2 

suspended, 3-80 

G 

Gag system variable, 2-100 
GAMMA function, 1-14 
Global names, erasing, 3-28 
Grade down function 

dyadic, 1-90 

monadic, 1-87 



Grade up function 

dyadic, 1-99 

monadic, 1-96 
Greater than function, 1-22 
Greater than or equal function, 1-22 
Group members 

displaying, 3-35 
Group names 

displaying, 3-36 

erasing, 3-28 
Groups 

adding to, 3-33 

copying, 3-16,3-72 

defining, 3-33 

dispersing, 3-33 



H 



High minus sign 
printing, 2-129 

I 



I/O 

mode, 1-75 
Identification 

of users, 2-13 

of workspace, 3—93 
Identification number, VMS 

process, 2-120 
Identifier 

assigning a value to, 1-215 
Identity items, 1-187 
/IMAGE qualifier, 2-118 
Index generator function, 1-105 
Index Of function, 1-107 
Index of records, 1—75 
Index origin, 3-64 
Index origin system variable, 2-102 
Inner product function, 1—208 
Inner product operator, 1—29 
Input prompt, 2-170 
Input prompt system variable, 2-170 
Input time limit, 2-188 



lndex-5 



Integer 

random, 1-14, 1-45, 2-168 
Interpreter, APL 

version of, 2-202 
Interruptions 

preventing, 2-100 
Intersection function, 1-110 



Job number, user, 2-201 



M 



K 



Key-paired character set, 2—47 



Labels 

list of, 2-131 
Laminate function, 1-34 
Latent expression system variable, 2-108, 

3-51 
Left context system variable, 2-104, 2-215 
Length 

of output lines, 2—144 
Less than function, 1-22 
Less than or equal function, 1-22 
Limit 

time, 2-185 
Line 

length of output, 2-144, 3-91 

wrapping output, 2-145 
Line counter, 2—106 
Line counter system function, 2-106 
Local symbols 

status of, 3-83 
Logarithm function 

dyadic, 1-17 

monadic, 1-12 
Logical functions, 1-21 
Logical operations, 1-22 
Lowercase alphabetics system function, 
2-15 



Magnitude function, 1-14 
Mailbox system function, 2-120 
Map system function, 2—111 
Match function, 1-113 
Matrix divide function, 1-116 
Matrix division, 1-116, 1-119 
Matrix inverse function, 1-119 
Matrix operations, 1-116, 1-119 
Matrix product of arrays, 1-209 
Maximum function, 1—18 
Membership function, 1-121 
Messages 

displaying during load, 2-109 

error, A-l 

preventing, 2—100 

secondary error, 2-183, A-l 

shorter error, 2-183 

signaling a, 2—172 

text of last error, 2—80 
Minumum function, 1—18 
Minus sign, 1-11 
Mixed functions, 1-1 

primitive, 1-22 
Monadic ceiling function, 
Monadic format function, 
Monadic functions, 1—1 

scalar, 1-2 

system, 2-5 
Monadic grade down function, 1—87 
Monadic grade up function, 1-96 
Monadic transpose function, 1-161 
Multiple arguments in user-defined ops, 

1-219 
Multiplication function, 1-16 



13 
-79 



N 



Name classification system function, 2-126 
Name list system function, 2-131 
Names 

classifying, 2-126 

directory of workspace, 3-47 
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Names (cont'd) 

displaying functions, 3-31 

displaying operators, 3-62 

distinguished, 2-2, 2—4 

erasing global, 3-28 

lists of, 2-131 

of group members, 3-35 

types of, 2-127 

workspaces, 3-93 
Nand function, 1-21 
Natural logarithm function, 1-12 
Negative function, 1-11 
Negative numbers 

recognition of, 2-89, 2-129, 2-204 
Negative sign 

output representation, 2-129 
Next-record pointer, 2-165 
Niladic system functions, l-A 
Nonprintable characters, 2-32 
Nor function, 1—21 
Not equal function, 1-22 
Not function, 1-21 
Null password, 3-71 
Numbers 

comparing, 2—56 

converting characters to, 2-88 

selecting from character string, 2—89 
Numbers system function, 2-135 
Numbers, types of 

error, 2-173 

user job, 2-201 
Numeric empty vector, 1-106 
Numeric input 

validating, 2-203 



Objects 

erasing named, 2-83 
Om system function, 2-136 
Operating system 

interacting with, 3-19, 3-74 

returning to command level, 3—56 
Operation execution 

delaying, 2-70 

gathering data, 2-122 



Operation execution (cont'd) 

interrupting, 2-179 

monitoring, 2-192 

stopping, 2-179 

suspending, 2-38, 2-179 

tracing, 2-192 
Operations, types of 

logical, 1-22 
Operations, user-defined 

debugging, 2-122, 2-179, 2-192 

displaying names, 3-62 

establishing, 2-98 

listing names, 2-131 

monitoring, 2-122 

restarting suspended, 2-108 

stopping, 2-179 

tracing, 2-192 

treating as data, 2-54 
Operators 

APL operators, 1-176 

backslash, 1-178 

dot, 1-178 

each, 1-191 

inner product, 1-29 

slash, 1-178 
Operators, types of 

locked, 3-81 

pendent, 3-80 

suspended, 3-80 
Or function, 1-21 
OR operation, 1-22 
Origin 

index, 3-64 
Outer product function, 1—205 
Output 

arbitrary, 2—17 

ASCII, 2-17 

controlling, 1-82 

formatting, 2-7 

untranslated, 2-17 
Output lines 

length of, 2-144 

wrapping, 2-145 
Output precision, 3-17 
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Overtake function, 1-154 



Pack system function, 2-138 
Password 

null, 3-71 

workspace, 2-147, 2-151, 2-154, 3-50, 
3-70, 3-77, 3-93, 3-94, 3-95 
Pervasive functions, 1—4 
Physical device number, mailbox, 2-120 
Pi times function, 1—12 
Pick function, 1-123 
PID, 2-29,2-201 
Pointer, next-record, 2-165 
Polynomials, evaluating, 1-29 
Power function 

dyadic, 1-16 

monadic, 1-11 
Precision of output, 3-17 
Primitive mixed functions, 1-22 
Print high minus system variable, 2-129 
Print precision, 3-17 

system variable, 2-142 
Print width, 3-91 
Print width system variable, 2-144 
Process identification number, 2-120 
Product (multiplication), 1-16 
Product, of array matrix, 1-209 
Prompts 

quad input, 2-170 

terminal type, 2-198 
Protected copy, quiet, 2-154 
Pseudo-terminal, 2-185 



Q 



Quad input prompt, 2-170 
Qualifiers, APL 

/ACCESS, 2-114 

/CHECK, 2-147, 2-151, 2-154, 3-15, 
3-50, 3-72, 3-77, 3-95 

/ENTRY, 2-113, 2-118 

/IMAGE, 2-118 

/INTO, 3-85 



Qualifiers, APL (cont'd) 

/LOWERCASE, 3-19 

/MAXLEN, 3-77 

/MECHANISM, 2-116 

/NOKEYPAD, 3-19, 3-74 

/NOLOGICALS, 3-19,3-74 

/NOSYMBOLS, 3-19,3-74 

/NOTIFY, 3-74 

/NOWAIT, 3-74 

/OVER, 3-85 

/PARENT, 3-8 

/PASSWORD, 3-15, 3-50, 3-95 

/TYPE, 2-114 

/VALUE, 2-113,2-118 
qualifiers, file organization, 2-21 
Query system commands, 3-3 
Query/Change system commands, 3-3 
Quiet copy 

system function, 2-147 

with protection, 2-154 
Quiet functions 

definition, 2-8 

list of, 2-8 
Quiet load system function, 2-151 
Quotient function (division), 1-16 

R 

Random integer, 1-14, 1-45, 2-168 

Random link system variable, 1-46, 2-168 

Range of functions, 1—1 

Rank of arrays, 1-150 

Ravel function, 1-130 

Read event flag system function, 2-77 

Reciprocal function, 1-11 

Records 

index for, 1-75 

releasing locked, 2-159 
Reduction function, 1-185 
Relational functions, 1-22 
Release system function, 2—159 
Remainder, 1-18 
Renaming a workspace, 3-78 
Replication function, 1-179 
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Replication system function, 2-161 
Report formatter system function, 2-93 
Represent function, 1-135 
Representation 

of an object, 2-207 

of canonical form, 2—98 

of negative sign, 2-129 
Reset system function, 2-164 
Reshape function, 1-138 
Residue function, 1-18 
Reverse function, 1-141 
Rewind system function, 2-165 
Right context system variable, 2-157, 2-215 
Roll function, 1-14 
Rotate function, 1-145 
Row-major order, 1-130, 1-138 



Saving workspace system function, 2—28 
Scalar functions, 1-1, 1-2 

arguments to, 1—5 

dyadic, 1-3 

monadic, 1-2 
Scalar product, definition of, 1-2 
Scan function, 1-201 

with associative argument, 1-203 
Secondary error messages, 2-183, A-l 
Selective assignment, 1-221 
Session variables, 3-4 

gag, 2-100 

tie, 2-190 

tt, 2-198 

vpc, 2-205 
Set event flag system function, 2-77 
$SEVERITY, global symbol, 2-174 
Shape 

array, 1-138, 1-149 

function, 1-149 
Shift 

left, 1-145 

right, 1-145 
Short error messages, 2-183 
Sign, high minus 

printing, 2-129 



Signal system function, 2-172 
Significant digits, 2-142, 3-17 
Signum function, 1-11 
Singleton, 1-3 

Sink output system variable, 2-176 
Size, workspace, 2-210 

maximum, 3—53 

minimum, 3-54 
Slash operator, 1-178 
Specification function, 1—215 
Squish quad, 2-32 
State indicator 

clearing, 3-82 

displaying, 3-80 

resetting, 2-164 
Status 

channel, 2-41 

file, 2-41 

function, 3-80 

local symbol, 3-83 

of executing lines, 3-84 
$STATUS, global symbol, 2-174 
Stop system function, 2-179 
Stopping programs, 2-179 
Storage available in workspace, 2-210 
Strand assignment, 1-218 
String search system function, 2-177 
Subprocess, VMS, 3-19, 3-74 
Subscripted assignment 

See Arrays Indexing 
Subset function, 1-152 
Subtraction function, 1-16 
Sum (addition), 1-16 
Suspended operations, 3—80 

executing, 3-85 

restarting, 2-106, 2-108 
Symbols 

status of local, 3-83 
System commands, 3-1, 3-5 

abbreviations for, 3-2 

form of, 3-2 

query, 3-3 

query/change, 3-3 

types of, 3-2 
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System commands, APL 
attach, 3-8 
charge, 3-10 
clear, 3-11 

clearing the state indicator, 3-82 
continue, 3—13 
copy, 3-15 
digits, 3-17 

displaying function names, 3-31 
displaying group members, 3—35 
displaying group names, 3-36 
displaying information about workspace 

creation, 3-68 
displaying operator names, 3-62 
displaying state indicator, 3-80 
displaying state indicator and executing 

lines, 3-84 
displaying state indicator and local 

symbols, 3-83 
displaying symbol table, 3-57 
displaying variables, 3-88 
displaying version number, 3-90 
do, 3-19 
drop, 3-21 
edit, 3-22 
erase, 3-28 
group, 3-33 
help, 3-38 
Input, 3-45 

listing workspace names, 3^7 
load, 3-50 

maximum workspace size, 3-53 
minimum workspace size, 3—54 
mon, 3-56 
off, 3-60 
origin, 3-64 
output, 3-65 
output width, 3—91 
owner, 3—68 
protected copy, 3-72 
push, 3-74 
save, 3-77 
step, 3-85 

workspace identification, 3-93 
workspace password, 3-70 



System commands, APL (cont'd) 

xload, 3-95 
System functions, APL 

accounting information, 2—13 

alphabetics, 2-14 

arbitrary output, 2—17 

assigning files, 2-20 

atomic vector, 2-32 

canonical representation, 2-54 

channel status, 2-41 

clear event flag, 2-77 

closing files, 2—52 

control characters, 2—58 

convert input, 2-88 

deassigning files, 2-60 

delay, 2-70 

device characteristics, 2-74 

erasing named objects, 2-83 

executing expressions, 2-221 

expansion, 2-85 

file sharing, 2-91 

fix function, 2-98 

form character matrix, 2-35 

form character vector, 2—35 

format, 2-7 

indexing Booleans, 2-136 

mailbox, 2-120 

map external routine, 2-111 

name classification, 2—126 

name list, 2-131 

numbers, 2—135 

packing data, 2-46, 2-138 

quiet copy, 2—147 

quiet load, 2-151 

quiet protected copy, 2-154 

read event flag, 2-77 

release, 2-159 

replication, 2-161 

report formatter, 2-93 

reset, 2-164 

saving workspaces, 2-28 

set event flag, 2-77 

string search, 2-177 

time stamp, 2-197 

underscored alphabetics, 2-16 
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System functions, APL (cont'd) 

unpacking data, 2-46, 2—138 

user load, 2-201 

validating input, 2-203 

visual representation, 2—207 

workspace available, 2-210 
System functions, types of, 2-3, 2-4, 2-9 

ambivalent, 2-7 

dyadic, 2-6 

form, 2—4 

monadic, 2-5 

niladic, 2-4 
System variables, 2—1, 2-9 

ASCII character set, 2-19 

form of, 2-2 

list of, 2-2 

maximum record length, 2-72 

types of, 2-2 
System variables, APL 

automatic save, 2-28 

comparison tolerance, 2—56 

display control, 2-62 

error message, 2-80 

index origin, 2-102 

input prompt, 2-170 

latent expression, 2-108 

print high minus, 2—129 

print precision, 2-142 

print width, 2—144 

random link, 2-168 

sink output, 2-176 

terminal line edit, 2—190 

terminal type, 2-198 

terse error messages, 2-183 

trap expression, 2—195 

vector process control, 2—205 

watched variables, 2-104, 2-157, 2-215 
System variables, APL primitives 

random link, 1-46 



Take function, 1-154 
Terminal 

width, 2-145 
Terminal line edit system variable, 2-190 
Terminal type system variable, 2-198 
Terse error messages system variable, 2—183 
Time 

connect, 2—13 

CPU, 2-13 

current, 2-197 
Time limit, 2-185 

input, 2-188 
Time limit system variable, 2—185 
Time out system variable, 2-188 
Time stamp system function, 2-197 
TPU editor, 3-22 
Tracing programs, 2-192 
Transpose function 

dyadic, 1—164 

monadic, 1-161 
Trap system variable, 2—195 
Trigonometric functions, 1-17 
Truth table, 1-21 
TTY 

character set, 2-47 

output of high minus, 2—129 



u 



Unconditional branching, 1-31 
Underscored alphabetics system function, 

2-16 
Union function, 1-170 
Unique function, 1-172 
Untranslated output, 2-17 
User identification, 2-13 
User load system function, 2-201 
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Validating input system function, 2-203 

/VALUE qualifier, 2-118 

Variables 

catenating different types of, 2-44, 2-138 

displaying, 3-88 

list of, 2-131 

session, 3—4 

system, 2-1, 2-9, 2-102 

see also System variables 

workspace, 3-4 
VAXTPU editor 

syntax form, 3—22 
Vector process control system variable, 

2-205 
Version number 

displaying, 3-90 
Version of APL interpreter, 2-202 
Version system command, 3-90 
Version system function, 2-202 
Visual representation system function, 

2-207 
VMS 

command execution, 3-19, 3-74 

signaling to, 2-174 

subprocess, 3-19 
VMS subprocess, 3-74 



Workspace (cont'd) 
clearing, 3-11 

copying objects from, 3-15, 3-72 
copying objects to, 2-147 
deleting, 3-21 
displaying information about creation, 

3-68 
expression executed when loading, 2-108 
loading, 2-151, 3-50, 3-95 
owner, 3-68 
password, 3-50, 3-70, 3-77, 3-93, 3-94, 

3-95 
renaming, 3-78 
saving, 3-13,3-77 
size, 2-210 

maximum, 3-53 

minimum, 3—54 
storage available in, 2-210 
variables, 3^4 

version saved under, 2-202, 3-90 
Workspace available system function, 2-210 
Workspace names 
directory of, 3-47 
displaying, 3-47 



Zero 

as argument in division, 1-16 



w 



Wait system function, 2—211 

Watch modes, 2-216 

Watch system function, 2—214 

Watchpoints, 2-215 

White space, 3-2 

Width, output, 2-145, 3-91 

Wildcards, 3-47 

Without function, 1-174 

Workspace 

APL CONTINUE, 3-13 
Automatic saving, 2-28 
automatically saving, 2-28 
backup, 2-28 
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How to Order Additional Documentation 



Technical Support 

If you need help deciding which documentation best meets your needs, call 800-343-4040 
before placing your electronic, telephone, or direct mail order. 

Electronic Orders 

To place an order at the Electronic Store, dial 800-DEC-DEMO (800-332-3366) using 
a 1200- or 2400-baud modem. If you need assistance using the Electronic Store, 
call 800-DIGITAL (800-344-4825). 

Telephone and Direct Mail Orders 



Your Location 

Continental USA, 
Alaska, or Hawaii 



Puerto Rico 
Canada 



International 
Internal 1 



Call 

800-DIGITAL 

809-754-7575 
800-267-6215 



Contact 

Digital Equipment Corporation 

P.O. Box CS2008 

Nashua, New Hampshire 03061 

Local Digital subsidiary 

Digital Equipment of Canada 

Attn: DECdirect Operations KA02/2 

P.O. Box 13000 

100 Herzberg Road 

Kanata, Ontario, Canada K2K 2A6 

Local Digital subsidiary or 
approved distributor 

USASSB Order Processing - WMO/E15 

or 

U.S. Area Software Supply Business 

Digital Equipment Corporation 

Westminster, Massachusetts 01473 



x For internal orders, you must submit an Internal Software Order Form (EN-01740-07). 
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